Response

Response Headers

The Revelian API will respond to each request with the following HTTP headers.

Header Description
Conversation-Id An ID that uniquely identifies a request/response pair in the Revelian system
Content-Type The MIME type of the body of the request. Variant of application/json
Content-Length The length of the response body in octets (8-bit bytes)
Date The date and time that the message originated

If you need to contact us about a specific request, providing the Conversation-Id will ensure the fastest possible resolution.

Example

Conversation-Id: c04c853b-b786-4552-be4a-23154bae5acd
Content-Type: application/json
Content-Length: 166
Date: Mon, 01 Jan 2016 10:00:00 GMT

HTTP Statuses

The Revelian API uses HTTP response codes to provide a coarse-grain indication of the success or failure of a request.

Code Description
200 - OK The request succeeded
201 - Created The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the self URL returned in the entity of the response
400 - Bad Request The request could not be understood by the server due to malformed syntax
401 - Unauthorized The request requires authentication. See Authentication for details
404 - Not Found Unable to find anything matching the combination of request URI and HTTP verb
429 - Too Many Requests Too many requests hit the API too quickly. See Rate Limits for details
500 - Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request

Errors

In conjunction with the HTTP status code finer-grain details of the error will be returned in the response body.

Property Description
conversationId An ID that uniquely identifies a request/response pair in the Revelian system
code Machine-readable code for the error encountered. See detailed endpoint documentation for specific codes
message Human-readable message for the error encountered

Examples

Resource not found (404)

An example response for a request to fetch an Organization Assessment that does not exist.

{
  "conversationId": "c04c853b-b786-4552-be4a-23154bae5acd",
  "code": "assessment_not_found",
  "message": "Unable to find assessment with identifier [f33e2408-0871-4433-b099-7227cc6e0f5e]"
}

Bad Request missing mandatory property (400)

An example response for a request to create a Position when the ‘title’ property is missing in the request body.

{
  "conversationId": "81966510-1793-42ac-a4ea-be8bfd3dc67e",
  "code": "mandatory_property_required",
  "message": "Missing required field 'title'"
}

Each resource provides details of errors that may be returned.

One of the core principles of REST is Hypermedia As The Engine Of Application State (HATEOS). Which means that every API resource must include URIs that identify the resource and the resources related to it. Hence all API resources are returned with a _links property which contains an array of relevant resource relationships.

Link objects adhere to the following structure.

Property Description
rel The type of the relationship
href A fully-qualified URL to the related resource

Every instance representation contains a self-referencing URI (i.e. the URI used to retrieve it). Where appropriate instance representations will, in addition to its ‘self’ link, also contain references to related resources.

Details of relationships are documented on each resource

Examples

Self link example

An example response containing a ‘self’ reference for an Assessment.

{
  "id": "{AssessmentId}",
  "code": "RCAT",
  "name": "Cognitive Ability Test",
  "description": "The Revelian Cognitive Ability Test will aid in maximising staff performance by identifying those individuals with the capacity to succeed in a diverse range of work roles.",
  "_links": [
    {
      "rel": "self",
      "href": "https://{BASE_URL}/assessments/{AssessmentId}"
    }
  ]
}

Relationship links example

An example response containing resource relationships for a Position

{
  ...
  "_links": [
    {
      "rel": "self",
      "href": "https://{BASE_URL}positions/{PositionId}"
    },
    {
      "rel": "assessments",
      "href": "https://{BASE_URL}/positions/{PositionId}/assessments"
    },
    {
      "rel": "candidates",
      "href": "https://{BASE_URL}/positions/{PositionId}/candidates"
    },
    {
      "rel": "invitations",
      "href": "https://{BASE_URL}/positions/{PositionId}/invitations"
    }
  ]
}

There is extra hypermedia reference information related to the paging information included in list resource representations. API resource endpoints that return multiple items will be paginated to 100 items by default.

Pagination information is present in the following response attributes.

Attribute Description
_links Contains next and/or previous links relative to the current page of items as appropriate
offset Non-negative number that defines where current page of items start from
limit Non-negative number that defines maximum number of items in the response
total Non-negative number that indicates the total number of matching items requested

It is advisable to use these links rather than attempt to construct your own URLs.

previous and next pagination links will only be present when such a relationship to the current page exists. For example, the results for the first page (i.e. offset of 0) would not have a previous link.

Example

An example of a Position list response where both next and previous pages are available.

{
  "positions": [ ... ],
  "_links": [
    {
      "rel": "self",
      "href": "https://{BASE_URL}/positions?offset=100&limit=100"
    },
    {
      "rel": "previous",
      "href": "https://{BASE_URL}/positions?offset=0&limit=100"
    },
    {
      "rel": "next",
      "href": "https://{BASE_URL}/positions?offset=200&limit=100"
    }

  ],
  "limit": 100,
  "offset": 100,
  "total": 500
}