General documentation

End points are grouped into two sets.

  • Graph QL endpoints allow you to query data

  • REST endpoints allow you to send modifications

Authentication

All APIs require an API Management subscription key obtainable though this portal.

Most APIs also require a valid JWT token with relevant permissions. There are different token types, for most users the following types are relevant

  • Tenant Token: Allows access to a single tenant

  • Employee Token: Allows access to a employee for the self-service portal

  • Training Provider Token: Allows access to a single training provider

Note that some APIs include a tenant-id or training-provider-id header. These are not required when using a tenant or training-provider token and can be omitted from the request.

Graph QL

Retrieving data is done using graph QL according to the 2021 specifications. We currently provide query support only, functionality such as mutations and subscriptions is not provided.

The following general features/structure is used:

  • Top level list employ cursor based paging.

  • Most lists by default filter disabled record (only record with disabled set to false are returned). This includes both top an nested record. For example when querying an employee with profiles only active employees and profiles will be returned.
    To access disabled record include the argument `includeDisabled: true` e.g. 'query{ employees(includeDisabled: true) { ... } }', unless this is include querying disabled records is not possible (filter 'disabled: { eq: true}' has no effect unless includeDisabled is set to true)

REST

Are used for all modifications.

The following general rules apply:

  • Most commands are idempotent, meaning that executing the same request twice will not have additional side-effects, e.g. calling PUT twice will only create the record once and both request will succeed.
    Because of this it is required that all request contain an identifier including create PUT requests. It is the callers responsibility to provide a valid unique (randomly generated) UUID.

HTTP Methods

  • PUT is used to create records

  • PATCH is used to update records, it is recommend but not required to only send changes.

  • POST for all other requests

  • Most types have POST disable/enable methods to Soft-delete records

HTTP Status codes

The following standard codes are used

  • 200 OK - For a successful operation with response

  • 202 Accepted - For a request that was accepted for processing but has not been completed.

  • 204 No Content - For a successful operation without response

  • 400 Bad Request - The format of the request is invalid. This may also occur if required fields are missing or in case of data-type mismatches (e.g. incorrectly formatted GUID).

  • 401 Unauthorized - The request is missing or has presented invalid authorization credentials.

  • 403 Forbidden - The requested operation was refused because of authorization restrictions.

  • 422 Un-processable Entity - Specifically used for validation of request data. In most cases these validations errors are intended for the end user. The errors object typically contains a list of properties and error codes that can be used to identify the specific issue. Note that the property field may not refer directly to a property in the request.

  • 429 Too many requests - The number of request has exceeded limitations. Subscription and sources can only submit a limited number of requests per interval.
    If this code occurs new requests should not be sent until the interval indicated by the 'retry-after' header has expired, these will be rejected with the same error.

Most errors that are solvable by the caller will have content type application/json+problem using RFC 7807: Problem Details for HTTP APIs (rfc-editor.org) containing details about the error. Including codes that can be used to localize errors.

Formats

For all endpoints the following formats are used:

  • Numeric values should use . (dot) as the decimal separator: e.g. 123.56

  • Date-Time values should use ISO 8601 - Wikipedia including a time zone. e.g. 2007-04-05T12:30-02:00. When using other formats or omitting the time zone the results may be unexpected.

  • Date for date only fields also use ISO 8601 e.g. 2007-04-05 if a time is provided this is ignored. Time zone should NOT be specified for date only fields, these will be converted to UTC prior to storage and may result in unexpected results.