REST API » Introduction

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.

Objects	haplo_api_object_v0
Users	haplo_api_user_v0
Files	haplo_api_file_v0

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	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": "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": "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.