Introduction

API Style

The API is an JSON REST API accessed via HTTPS.

The endpoints are all relative to the system base URL. The hostname is used by the server to identify the customer’s application. For example, if the system URL used by the users is http://app.example.org then given the endpoint /api/example the URL http://app.example.org/api/example should be requested.

API Implementations

This style of API is used for APIs managing different types of data within Haplo systems. You should install the plugins for the specific APIs that your application needs to use.

Response

Every request to the API will receive a response in JSON format with the following structure

  • success
  • kind

kind contains a code that defines where the response is coming from. In addition to the kinds provided by each API implementation, there are the following generic kinds:

Kind Meaning
haplo:api-v0:generic:not-permitted The user is not authorised to access the API. Returns with HTTP status 401
haplo:api-v0:generic:exception The request failed with an error. Returns with HTTP status 400
haplo:api-v0:generic:no-response The API implementation did not respond to the request. Returns with HTTP status 404

success can have a value of true or false, and tells you whether the request succeeded or failed. If the request succeeded, more data defined by the specific API you are using can be expected to be included in the response.

Example successful response body

{
    "success": true,
    "kind": "haplo:api-v0:user:update",
    "user": {
        "id":130,
        "nameFirst":"Test",
        "nameLast":"User",
        "name":"Test User",
        "code":null,
        "email":"test@example.com",
        "ref":null,
        "isGroup":false,
        "isActive":true,
        "isSuperUser":false,
        "isServiceUser":false,
        "isAnonymous":false,
        "localeId":"en",
        "directGroupMembership":[]
    }
}

If the request has failed, instead of API specific information, there will be an error field, containing a field message with any information that can be returned about what has gone wrong to help diagnose the problem. The response will also be returned with an appropriate HTTP status code for the reason behind the failure.

Example failed response body

{
    "success": false,
    "kind": "haplo:api-v0:generic:exception",
    "error": {
        "message": "org.jruby.exceptions.RaiseException: (JavaScriptAPIError) User must have a non-empty String nameFirst attribute"
    }
}

Authentication

All requests must be authenticated using an API key. It is recommended that you set a restrictive request path so that the API key can only access the intended APIs.