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 then given the endpoint /api/example the URL 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.

Objects haplo_api_object_v0
Users haplo_api_user_v0
Files haplo_api_file_v0


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 HTTP status
UNAUTHORISED A generic permissions error was encountered. 403
INVALID-API-KEY The provided API key was not valid. 403
haplo:api-v0:generic:not-permitted The user is not authorised to access the API. 403
haplo:api-v0:generic:exception The request failed with an error. 400
haplo:api-v0:generic:no-response The API implementation did not respond to the request 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": "",
        "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": "User must have a non-empty String nameFirst attribute"


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.