Generic JSON Response

Author: Twan van der Schoot (TvdS)

Date: 20200324

Version: 1.4.1

Status: final

Version History

Change History

Date	Version	Changes	Author
20170515	1.0	Creation	TvdS
20170522	1.1	400 as explicit semantic error response code	TvdS
20170529	1.2	Added section on available servers and servers added to generic response and wrong status(AUR17002-27)	TvdS
20170601	1.3	Added JSON Schema Validation specification for the generic response	TvdS
20170628	1.4	Added reserved GJR status code values + explanation (AUR17002-47)	TvdS
20200324	1.4.1	Simplified document.	BB

Introduction

The Aurum Aurope REST APIs all deal in a uniform way with HTTP responses:

1. If the HTTP response status code is 200, 201, or 400 the response entity is a JSON object as described in §Generic JSON response Object.
2. If the HTTP response status code is anything else, the response can contain a body, but should be ignored.

Generic JSON response Object

Every JSON response object contains the following mandatory properties:

1. timestamp: A timestamp in ISO8601 indicating the time of the creation of this response. If the request Date header (RFC2616 §14.17) contained a time with a timezone specification, the timestamp will adopt that same timezone. If no Data header is found in the request, the server will sent a timestamp in UTC.
2. status : An integer. 0 if everything is okay, any other number signifies a problem.
3. data: The API response. Can be an empty JSON object: {} especially when status != 0.
4. servers : A JSON array containing alternative Aurum servers for the relevant REST API. These can be used as fallback servers when the current server becomes unreachable.

The following data elements in the response object are optional:

1. message: A string containing a free text message when some issue or error has occurred. This is an informal message for development purposes and should not be parsed. Can be empty.
2. uimessage See §Server User Interface Message.

Generic JSON Response status code

The following status codes in a GJR are reserved:

status code	description
0	The request was handled succesfully
1	The request was rejected because of an invalid entity
2	The request was rejected because one of the fields didn't pass the validation
3	The request was rejected for some unspecified / unexpected reason

Server User Interface Messages

The uimessage property can provide multi-lingual internationalized messages for issues.
The property names are strings identifying the language accoording to RFC2616 §3.10. Examples are "en-US" and "nl-NL"

Examples

An example of a successful generic response:

{
  "timestamp": "2017-05-15T15:10:03.234+01",
  "status": 0,
  "message" : "message",
  "data" : {«JSON value»},
  "servers" : ["srv1.aurumeurope.com", "srv2.aurumeurope.com"]
}

An example of a failed generic response with a uimessage property:

{
  "timestamp": "2017-05-15T15:10:03.234+01",
  "status": 2,
  "uimessage" : { "nl_NL" : "het bericht", "en_GB" : "The message", "en_US" : "The squeak"},
  "message" : "simple technical message in english",
  "data" : {},
  "servers" : ["srv2.aurumeurope.com", "srv3.aurumeurope.com"]
}

An example of failed generic response with an empty data property and no uimessage. A message property can be an empty string:

{
  "timestamp": "2017-05-15T15:10:03.234+01",
  "status": 3,
  "message": "Somthing went wrong.",
  "data": {},
  "servers": ["srv3.aurumeurope.com", "srv1.aurumeurope.com"]
}

Important note for developers using the Aurum REST APIs

If, according to an Aurum REST API specificaton, an HTTP response contains a response entity body, then that response is always a generic JSON response (GJR) as described in this document. However in the REST API Specifications we only document what the developer would expect in the data-field as a JSON response entity.

This is because OpenAPI does not allow you to specify a wrapper object.

---