Public API for ISMS.online

Public API for the ISMS.online service.

The API is based on REST-like principles and will broadly follow resourceful REST design conventions.

1. Authentication

The API uses Bearer token to authenticate endpoints. In order to generate your token you should send a POST request to the /v1/authentication endpoint with your API secret as a parameter. To find your API secret_key you need to get this via your ISMS.online web account. If you are unsure where to find this information please speak to your account administrator.

An example request to the authentication endpoint should look something like this:

curl --request POST \
  --url https://rest.api.r1.isms.online/v1/authentication \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "secret_key": "<secret-key>"
}'

In response you will receive your token.

{ "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOjcxOTksImV4cCI6MTcxMDc2NTM2NiwianRpIjoiNzNjNGMyMzUtNGYyNy00NzEyLWFkN2UtOTFkNTAwOTYyYTRmIn0.JAVsthszbfBTUeks2M0rcZ2WGcimNJrGEXo4xTGE36U" }

This token can then be used to access all other endpoints of the API e.g.

curl --request GET \
  --url https://rest.api.r1.isms.online/v1/tracks \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOjcxOTksImV4cCI6MTcxMDc2NTM2NiwianRpIjoiNzNjNGMyMzUtNGYyNy00NzEyLWFkN2UtOTFkNTAwOTYyYTRmIn0.JAVsthszbfBTUeks2M0rcZ2WGcimNJrGEXo4xTGE36U'

2. Request Bodies and Responses

Responses

Successful responses from the API will always consist of a JSON object at the top level. The API will never return an array as the top level data structure.

Typically, successful responses will consist of 3 top level keys:

{
  "data": {},
  "links": {},
  "meta": {}
}

Request Bodies

Request bodies are only accepted on POST and PATCH requests. When updating a single resource (as opposed to a collection) the top level object will be a JSON object {...} where each key of the object represents the corresponding field on the underlying resource e.g.

{
  "name":"Security Incident: Laptop Left on Train",
  "description":"Staff member left laptop with sensitive information on the train"      ...
}

3. Pagination

Our API implements conventional Limit Offset pagination. When requesting a collection of resources we allow 2 query parameters to help users navigate multiple pages page and limit. These are optional parameters and if non provided will default to 1 and 10 respectively -- limit must be provided in multiples of 10, up to a maximum of 100 e.g.

curl --request GET \
  --url 'https://rest.api.isms.online/v1/tracks/0a5beb9d-0495-4b85-bfd6-5c200da671dd/tickets?page=3&limit=50' \
  --header 'Accept: application/json' \

To help you iterate over a collection of resources, we provide additional data about the total_count of results in the meta object of the JSON data response object e.g.

{
  "data": [
    { "id": "203d547e-f871-43e3-9248-d428176bb439", ... },
    { "id": "3cf43b13-5b05-40d6-962f-296f5afd475a", ... },
    { "id": "0a5beb9d-0495-4b85-bfd6-5c200da671dd", ... }
    ...
  ],
  "links": {
    ...
  },
  "meta": {
    "page": {
      "page_number": 1,
      "total_count": 673
    }
  }
}

Footnotes

If you have any questions about how our API works, or how to get started, don't hesitate to get in touch with our Customer Support team. We are available at support@isms.online