RESTful API

Grexx Platform offers a RESTful API as standard on every environment (Development, Testing, Acceptance, and Production). This is useful if you want to allow other applications or systems to interact with your Grexx Platform application programmatically.

The API exposes endpoints that can be used to retrieve data from cases, datasets, forms, or tasks, and create or submit tasks. You can make calls to the API under /api/v1 from any environment. For example you could make a call to https://boxx-accept.grexx.today/api/v1/case/1:123:456/task/456789.

API specification

The API is described based on the OpenAPI Specification version 3. You can find the API that applies to your application and environment by appending /api/spec to your application's base URL.

To make reading the API specification easier, we recommend using a tool such as Swagger UI or Redoc.

To read the API specification using Swagger UI, ensure Docker is installed and then run the following command, replacing the URL with the URL of your environment followed by /api/spec.

In Powershell:

docker run -p 8089:8080 -d -e URL='https://ENVIRONMENT_HOSTNAME/api/spec' --name swagger-ui swaggerapi/swagger-ui

In cmd:

docker run -p 8089:8080 -d -e URL=https://ENVIRONMENT_HOSTNAME/api/spec --name swagger-ui swaggerapi/swagger-ui

To view the API specification, go to http://localhost:8089. You can also run and test the API from here.

Swagger also offers an editor with which you can generate a client in almost any programming language. To launch the Swagger editor, run the following command:

docker run -p 8088:8080 -d --name swagger-editor swaggerapi/swagger-editor

To open the editor, go to http://localhost:8088. Click File > Import URL and enter https://ENVIRONMENT_HOSTNAME/api/spec (replacing the URL with the URL for the relevant environment, as before). Then click Generate Client and select your preferred language.

API authentication

Each request to the API must be authenticated to ensure the requestor has permission to view the data or perform the activity. Like everything in Grexx Platform, authentication is based on cases. This is the same as when you log in to your application via a browser: you log in as a User case and are authenticated by XXID. When you navigate to different views or initiate activities, Grexx Platform checks whether the current User case belongs to a role with rights to see the widgets on a view and/or perform the requested activity.

An API request must be performed by a case. Rather than using the User casetype, you can set up a different casetype, such as Organization. You can then add Organization cases (such as "Acme Corp" or "Janssen BV") to one or more roles in order to grant those cases permissions. Although you cannot log in as "Acme Corp" or "Janssen BV" via XXID, you can use these cases to make requests via the API.

When you grant permissions to roles designed for use by User cases, you give those roles rights to activities, widgets, and navigation items. The same rights give access to activities and widgets via the API. Depending on the API endpoints you want to use, you may also need to grant roles permission to read data in forms or datasets directly.

To allow a case (such as "Acme Corp" or "Janssen BV") to perform activities or retrieve data via the API:

Optionally create a dedicated role name for API use. This is good practice because it allows you to manage what is exposed via the API separately from permissions for logged in users.
From your Studio, grant the API role rights on the appropriate activities, widgets, forms, and/or datasets.
If you want to add cases to a platform role (rather than a direct or indirect casetype role), create a form activity so that you can add cases to the multivalue attribute for the API role.
From your DTAP environment, add the relevant cases (such as "Acme Corp" or "Janssen BV") to the API role.

For more information about creating roles, granting rights, and adding cases to roles, see Manage users and permissions.

Web service keys

Authentication as a case involves the correct combination of a client ID and a client secret. We call this combination a web service key.

To allow a case (such as "Acme Corp" or "Janssen BV") to authenticate to the API, you need to create one or more Web service key cases for that case:

Import the Web service key casetype from Grexx Marketplace. This casetype automatically generates a client ID and secret and includes a view where you can see this data.
Add a casetype activity that creates a new Web service key case to the casetype that will make the API request (such as the Organization casetype).
From the relevant DTAP environment, use the casetype activity generate one or more web service keys from the cases that will make API requests.

You can view the web service key, including the client secret and client ID from the default view for the Web service key case. You can use these details to authenticate to the API and generate a token, as described below.

Note the following:

A Web service key case always belongs to its parent case (casemeta.parentCase). You cannot change this and it is not possible to attach a web service key to another case.
You can give a Web service key case a description and an expiry date. This is useful when generating multiple web service keys for a single case.
A web service key is no longer valid once the Web service key case has been closed. If you enter an expiry date, the Web service key case closes automatically on the specified date. A web service key is also no longer valid once its associated parent case has been closed.

Tokens

With the correct combination of client ID and client secret, you can request a (session) token per API session. A token has a short validity (usually 10 minutes) and allows you to carry out the actual API requests. Pay close attention to the expiry date of your token and make sure you renew your token on time.

We follow the OAuth 2.0 Client Credentials protocol. To request a token, make a request to https://ENVIRONMENT_HOSTNAME/oauth/access_token and supply the client ID and client secret. For more details, refer to the API specification. For an overview of the client credentials flow, refer to the Auth0 guidance.

Note:

Only use the web service key to request a token. Do not send your web service key in your subsequent API requests; these should be authenticated using the short-lived token.

API requests

When making API request ensure you include the authorization token in the request header using the format: Authorization: Bearer 12345678-wxyz-9876-abcd-314159265359

Tip:

For testing purposes, you can use Swagger UI to generate API requests and view the responses. To do so, authorize the connection using a suitable client ID and client secret generated for a case on the same DTAP environment.

Encoding

All strings should be encoded in UTF-8 format.

Form endpoint

When using an endpoint to retrieve a form, specify the required variant using the format query parameter:

Format	Comments
`simple`	For data transfer: Returns a simple JSON in which the keys are the field's `externalReference` (or the field ID if no external reference has been set). Value is the value of the field.
`extended`	For a GUI: Provides some field information and contains a nested structure of groups and fields.
`full`	For a GUI/app: Provides all the form information including form logic.

To retrieve a form via the API, you must grant rights to that form from the Studio, as described above.

Send files

There are two ways in which you can send a file as part of an API POST request:

As a base64-encoded variant of the bytes of the file.
As a URL.

To send a file using base64 encoding, use the following format for the value of the attribute in question. Replace the values for content, contentType, and originalFilename as required:

{
    "type": "att",
    "encoding": "base64",
    "content": "iVBORw0KGgoAAAxHwzYtvZI6tKe+Y7Ze2Jf7aV9tVMsIs5iA2w0YYakmLUmQ7pzTitgxcR0Wcw50B8zUq1bESMYO/fsyJ9r41kEMH1L+YwTrvonnLg/1jZWwOyAKNiAAAAAElFTkSuQmCC",
    "contentType": "image/png",
    "originalFilename": "image.png"
}

To send a file using a URL, use the following format for the value of the attribute in question. Replace the values for url, contentType, and originalFilename as required, and ensure the URL is visible to Grexx Platform:

{
    "type": "url",
    "url": "https://example.com/link/to/my/image.png",
    "contentType": "image/png",
    "originalFilename": "image.png"
}

Note:

For both variants, all fields are required. A request may contain a maximum of 20 MB of base64-encoded files. Files larger than 20 MB must always be sent using the URL variant.

API specification​

API authentication​

Web service keys​

Tokens​

API requests​

Encoding​

Form endpoint​

Send files​