Introduction

This document describes the inmemory4 and memographics (from this point called the app) API for external systems.

API notation and code examples will be shown as follows:

Short description Since: Implemented since this API version

• Client-URI: https://<im4>/api/<api-uri> (valid for Client auth)
• Request-type: <HTTP request type>
• Parameters:
  {parameter1} (data type): value or description
  {parameter2} (data type): value or description
  ...
• Return data:
  (data type): value or description

Additional information

Agency setup

Every agency configured in the app can set up their own list of authenticated external systems. These external systems are technically connected to a separate user account in the app. This separate user belongs to an agency and the agency administrator has to enable the external API functionality in order to configure the external systems. These external systems will be assigned a Client id and a Client key which needs to be used while accessing the API.

The list of authenticated external systems is available in the agency administration part of app.

Data format

In general, this API is based on HTTP POST requests where input is given as JSON formatted data, or HTTP GET and HTTP DELETE requests where parameters are part of the URI (“REST”-style). There may be exceptions to this which will be fully documented in each API call.

API usage

Request authentication token

In order to be authenticated with the app, external systems needs to receive an authentication token. Authentication tokens are long-lived and never expire. They can however be revoked at any time by the issuing agency. To receive a token, the external system needs to make an API call:

URI: https://<im4>/oauth/token

• Request-type: POST
  
• HTTP Headers: none
  
• Parameters:
  {grant_type} (string): ‘client_credentials‘
  {client_id} (integer): <given client id>
{client_secret} (string): <given client key>
{scope} (string): ‘*‘
  All parameters must be sent as form-data.
• Return data (JSON):
  {token_type} (string): ‘Bearer’
  {expires_in} (int): Number of seconds until expiration
  {access_token} (string): Generated access token

The returned access_token needs to be provided in any subsequent API calls.

General HTTP headers

For every subsequent API call after authentication, the access_token needs to be specified as part of the HTTP headers:

URI: https://<im4>/<api-call>

• Request-type: POST, GET or DELETE
• HTTP Headers:
  Accept: application/json
  Authorization: Bearer <access_token>

The <im4>-part of the URI is comprised of the server address to the app instance, plus additional paths for the API call:

https://<server address>/api/<api-call>

Please use the proper <im4> variant accordingly in the rest of this specification. Also, the server returns HTTP status codes according to the result of the request.

HTTP status codes