General endpoint structure#

The Argus API uses a REST structure, with the general layout desribed in this document.

Result set#

All endpoints - including those returning a single object -have a common result set format of the form :

{
  "responseCode" : 200,
  "limit" : 25,
  "offset" : 0,
  "count" : 113,
  "size" : 25,
  "data" : [...]
}

The value data contains the real result from the endpoint, which may be a list or a single object, depending on the endpoint.

Empty results#

For list result endpoints, an empty result will be returned as an empty list.
For a single result endpoints, an empty result may return data value null, or return status code 404 if the endpoint is not valid.

`count` and `size`#

For searching endpoints, the value count will give the total number of results for the given filtering parameters.

The size will simply state the number of values returned in a list result. For a single result, size should be 0.

If counting is not implemented (such as for single object endpoints), the value of count will be 0.

If counting takes too long, it may time out, in which case the value of count will be -1.

Identifying fields#

Clients should beware which fields on an object are considered identifying. Most objects have an id, which is a numeric value or a UUID. This is typically a unique field which will never change as long as the object exists.

In addition, many fields have a shortName field, which is a human-readable, but still programmatically usable field, which is normally a readable single word, containing a unique name for the object. Although shortnames are possible to change, they are usually considered stable and unique, as they provide reference points both in Argus code and in integrations.

Other name fields however, as well as localizedName and description, are typically considered visual names only, and should not be used as identifying fields.

Info objects#

Returned objects that have a reference to other objects, typically use Info objects to provide information about the referenced objects.

An info object is a reduced version of the referenced object, typically containing the ID and the key properties (name, customer) of the referenced object.

Clients which need to show more of the referenced object than what is available in the info object, should fetch that object from its own endpoint. If this is done a lot, it may be wise to implement a cache for this purpose.

Error codes#

There are some general error codes used across all endpoints:

200 OK: No error, request completed successfully
201 Created: No error, request completed successfully, creating a new entity
401 Unauthorized: The session or API-key provided is not valid, so the service cannot validate the request to any users permissions
403 Forbidden: The current session or API-key is not permitted access to the requested operation. This may be a specific constraint (no access to the specified object), or a general constraint (no access to the requested operation at all)
404 Not Found: If requesting a specific resource, the system may return 404 if this resource is not found / not available. When listing/filtering entities, the result will be empty if no matching values are found.
405 Method Not Allowed: If requesting an endpoint with unsupported content type specifications, this may return error 405. Make sure the content-type header is correctly set.
412 Precondition Failed: This code may be used to indicate that the request is invalid, either because some constraint is not satisfied, or because some of the provided parameters are invalid. See Parameter errors

In addition, endpoints may have their specific error codes, which are documented in the API-docs for the service.

Parameter errors#

If request contains invalid/wrong parameters, the service will return a 412 status code.

The result set will then contain a FIELD_ERROR message:

{ 
  "responseCode" : 412,
  ...,
  "messages": [
    {
      "message": "Invalid value for field",
      "messageTemplate": "invalid.field.value",
      "type": "FIELD_ERROR",
      "field": "fieldname",
      "parameter": null,
      "timestamp": 1491810313412
    }
  ],
  "currentPage": 0
}

If the error is more general, and not associated to a specific field (such as a specific constraint encountered when processing the request), the result set will contain an “action error” message and no specific field name.

Retrieving objects#

GET operations are guaranteed read-only, meaning that they will not change data in any way.

Endpoints retrieving single entities, or lists of entities are using the GET method.

The general URL structure for this is :

GET /module/version/entity?queryParameters

which will list all available entities of this type, optionally filtered by the provided parameters.

or:

GET /module/version/entity/id

which will fetch a single entity with the given ID.

Advanced search#

The exception is advanced search endpoints which accept a JSON body with advanced search criteria, these are using POST.

The general URL structure for the search endpoints is:

POST /module/version/entity/search

with a POST body containing the search criteria:

{
  "field" : [ "value1", "value2", "..."],
  "other_field": "value"
}

Adding new objects#

Endpoints for adding new data are using the POST method. The general URL structure for this is:

POST /module/version/entity

with a JSON body defining the new object:

{
  "field" : "value",
  "booleanField" : true,
  "otherBooleanField" : false,
  "collectionField" : ["val1","val2"]
}

If creating the object violates any constraints (such as name uniqueness etc), the operation will fail with HTTP 412 (Parameter error).

Add-endpoints return the created object, which also includes the id field of the c reated object.

On objects with created or lastUpdated fields, these fields are automatically set by the service.

See the API documentation for JSON structure.

Updating objects#

Endpoints for updating existing data are using the PUT method. The general URL structure for this is

PUT /module/version/entity/id`

with a JSON body defining the new object.

{
  "field" : "updated value",
  "booleanField" : false,
  "removeFromCollectionField": ["val1","val2"],
  "addToCollectionField": ["val3","val4"]
}

Generally the update operations have a list of optional fields, and only specified fields will be updated.

If an object’s field is set, the value of that field will be set on the specified object.

In the example above (relative to the object created in the previous “add”-operation):

field and booleanField are set new values
otherBooleanField is not touched.
collectionField is updated by removing two existing values, and adding two new values.

Update-endpoints return the updated object, after the specified field changes have been applied.

Objects with lastUpdated fields are automatically updated by the service.

See the API documentation for JSON structure. for JSON structure.