Common Service API

API Overview

AquaCUE Web Services APIs use RESTful web services to deliver data in JSON. Most programming environments have readily available libraries for creating HTTP requests and parsing the responses.

Common Service API

All AquaCUE Web Services follow the common services API design.

HTTP Status Codes

These are the standard response codes all AquaCUE services return. See each API for specific details about codes.

Code	Desc
200 OK	Request accepted and there should be some content, assume the operation is complete
202 Accepted	Request accepted but processing is not complete. The location header points to a URL that shows the progress or final result
204 No Content	Request accepted but there is no more detail/content about it, assume the operation is complete
302 Found	To redirect to another URL, such as a download
400 Bad Request	Badly formatted request, i.e. the JSON is invalid as opposed to an validation failure (missing required field, date not a date) which is 422
401 Unauthorized	No Authorization header, or not authorized
403 Forbidden	User does not have permission
404 Not Found	If any specific resource or page is not found, i.e. hwr/account/blah. In the case of list calls (i.e. GET /hwrruns) an empty array will be returned
409 Conflict	Generally, on create (POST) there is a collision, see the APIs for specifics
412 Precondition Failed	Generally, on update (PUT/PATCH) there is an issue with changing the resource, see the APIs for specifics
422 Unprocessable Entity	Request is syntactically correct but the entity is not valid, a required field is missing or a date is out of range
5xx	Internal server error

Response Objects

All services respond with no ambiguity in object type, that is, a client will be able to deterministically get a response based on the HTTP response code. Depending on the HTTP response code the same object is returned. Some responses use object “wrappers” for pagination.

When an API returns 4xx codes, they are standard error responses.

A 2xx code will return a JSON object as per the API.

Property Names

All JSON objects use camelCase, except uuids are the property with UUID suffixed, e.g. accountUUID, reportUUID, taskUUID etc.

type	desc
string	string
int	int
float	float
bool	boolean
Object array	an array of element type Object
uuid	string quoted UUID. “3287912374838239853”
date	string quoted ISO 8601. “2015-02-03T13:04:24Z”
email	string quoted email address (limit 254). “frank@example.com“
url	string quoted url, may be relative. “/v1/svc/3323”

Pagination

The API allows for paginating through results sets. Results that are paginated are returned in a pagination wrapper object, with the actual objects under a results property. The API request must take a standard set of parameters that indicate the pagination criteria.

Parameters

param	type	desc
offset	int	Record number offset, starting at 0. The first record number after this offset is included in the results. Default: 0
limit	int	Max number of records to return, up to a max of 100. Less records may be returned Default: 50
sort	string	Field to sort on
dir	enum	desc | asc. Default: desc

Response Object

property	type	desc
total	int	the total number in the set
from	int	the record number of the first element in results. Record numbers start at 1
to	int	the record number of the last element in results
results	Object array	an array of the result objects – see API for type of object. It will be an empty array if total is 0, and may be empty if there are no results beginning at the requested offset

[sourcecode lang=”bash”]

{
“total”: 532,
“from”: 101,
“to”: 150,
“results”: [ {
MY OBJECT
]}
}

[/sourcecode]

API Codes

All services use a common API code format:

[sourcecode lang=”“bash””]
apicode:= [E|W|I|D]-tla-nnn
[/sourcecode]

Each service defines the possible error codes and their meanings.

i.e. E-HWR-200 or W-TSK-56

Code Arguments

Some codes might require arguments. These can be used when creating an error message, e.g. code E-HWR-301 might translate in en to “The cloned template ({1}) does not exist”, where {1} is the first argument value, e.g. “Winter Run”.

The optional args property in the error response is an array of string.

Reason Codes

Reason codes are non human readable points in the code that indicate the location of the API code or underlying reason for generating the code. They are chainable and a service should forward reason codes: If the HWR service calls the TSK service, which returns an error code and reason, the HWR should return a new API code (E-HWR-nnn) and chain the TSK reason code (HWR-client.tsk_TSK-run.py:56)

[sourcecode lang=”bash”]
reason:= tla-msg[_reason]*
msg:= anyalpha ^_
[/sourcecode]

Error Responses

A service that returns errors respond with a standard object that contains at least the code and reason.

{
  "code": "E-HWR-200",
  "args": ["a code argument"],
  "reason": "HWR-client.tsk_TSK-run.py:56
}

Common API Codes

These codes are common to all services.

HTTP Status	API Code	args	desc
400	E-API-400	status code	An internal issue caused by a bad request
400	E-API-450	lineNbr, colNbr	General JSON processing exception
400	E-API-451	lineNbr, colNbr	JSON parsing failed. Badly constructed JSON
400	E-API-452	lineNbr, colNbr	JSON mapping
400	E-API-453	lineNbr, colNbr	JSON generation. Could not generate JSON response
406	E-API-406		Accept response media type not supported
415	E-API-415		Content-Type request media type not supported
422	E-API-422	property:error, …	Validation failure. See API for description of required object properties
500	E-API-500		Internal Server Error

Authentication

The API uses HTTP basic access authentication to provide your applications with secure access to all data available to your account. In addition, all requests must go through our HTTPS endpoint, where all data transfer is encrypted through SSL. Using your AquaCUE username and password, you can use your programming library base64 method to create an HTTP Authorization header. For an explanation of this procedure, see: http://en.wikipedia.org/wiki/Basic_access_authentication.