API Responses
On Key API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource including one or more contextual hypermedia links. Use these links to request more information about and construct an API flow that is relative to a specific request.
Headers
The commonly used HTTP response headers are:
| Name | Description | Example |
|---|---|---|
OnKey-Trace-Context |
Trace context for the API request in the format <TraceId>_<SpanId>. Use the trace context to find the specific API request within the On Key logs and application telemetry. |
0HMPJIBRTS8N3:00000003_39314b75-fc08-4dc3-b005-cbdaa58af37a |
OnKey-Resource-Id |
Id of the resource created using a POST request. |
1582413583401002 |
OnKey-Resource-Location |
Uri for fetching the resource created using a POST request. |
api/tenants/{client}/{connection}/Modules/GEN/Languages/1582413583401002 |
OnKey-Request-Id |
Request Id for the Background Task created when submitting an asynchronous API request | 1582413583401002 |
OnKey-Request-Location |
Uri for polling the status of Background Task created using an asynchronous API request. | api/tenants/{client}/{connection}/Modules/System/BackgroundTasks/1582413583401002 |
OnKey-Job-Id |
Job Id for the schedule created when scheduling an asynchronous API request | cc4820be-e990-4161-85ff-eec4bbde2acb |
OnKey-Job-Schedule-Location |
Uri for getting the job schedule created when scheduling an asynchronous API request. | api/tenants/{client}/{connection}/Modules/System/Jobs/cc4820be-e990-4161-85ff-eec4bbde2acb/Schedule |
Content-Type |
Specifies the response format. Returned for operations with a response body. | Content-Type: application/vnd.onkey.entity+json |
Content Types
The supported content types for responses are:
| Name | Description | Docs |
|---|---|---|
application/vnd.onkey.notification+json |
Response contains errors, warnings and other information | Link |
application/vnd.onkey.entity+json |
Response contains the data for a resource | Link |
application/vnd.onkey.entitycollection+json |
Response contains a collection of data for resources | Link |
application/vnd.onkey.entitycollectionpage+json |
Response contains a pageable collection of data for resources | Link |
application/vnd.onkey.entitymetadata+json |
Response contains the metadata definition for a resource | Link |
application/vnd.onkey.entityenummetadata+json |
Response contains the property and enumeration metadata definition for properties that make use of an enumeration for a resource | Link |
application/vnd.onkey.entitydatabasemetadata+json |
Response contains the database metadata definition for a resource | Link |
application/vnd.onkey.entityexistscheckcollection+json |
Response contains a collection of entity exist check results | Link |
application/vnd.onkey.assetregistertreenode+json |
Response contains the data for a node within the Asset Register trees | Link |
application/vnd.onkey.assetregistertreenodecollectionpage+json |
Response contains a pageable collection of Asset Register tree nodes | Link |
application/vnd.onkey.resourceschema+json |
Response contains the schema definition for a resource | Link |
application/vnd.onkey.resourceschemacollection+json |
Response contains a collection of schema definitions for resources | Link |
application/vnd.onkey.resource+json |
Response contains a resource definition | Link |
application/vnd.onkey.resourcecollection+json |
Response contains a collection of resource definitions | Link |
application/vnd.onkey.resourceaction+json |
Response contains a resource action/operation definition | Link |
application/vnd.onkey.resourceactioncollection+json |
Response contains a collection of resource action/operation definitions | Link |
application/vnd.onkey.customresourceaction+json |
Response contains the definition of a customisation for a resource action/operation | Link |
application/vnd.onkey.template+json |
Response contains a UI template definition | Link |
application/vnd.onkey.templatecollection+json |
Response contains a collection of UI template definitions | Link |
application/vnd.onkey.customtemplate+json |
Response contains a customised UI template definition | Link |
application/vnd.onkey.spec+json |
Response contains an OpenAPI v2/v3 specification for a Module or System | Link |
application/vnd.onkey.menu+json |
Response contains the System menu | Link |
application/vnd.onkey.modulecollection+json |
Response contains a collection of Module definitions for the System | Link |
application/vnd.onkey.metadatacollection+json |
Response contains a collection of metadata definitions for resources | Link |
application/vnd.onkey.enummetadata+json |
Response contains an enumeration definition | Link |
application/vnd.onkey.enummetadatacollection+json |
Response contains a collection of enumeration definitions | Link |
application/vnd.onkey.metadatatree+json |
Response contains a metadata tree definition for a resource | Link |
application/vnd.onkey.metadatatreepathmapcollection+json |
Response contains a metadata tree path map definition for a resource path | Link |
application/vnd.onkey.userdefinedquerypage+json |
Response contains a pageable collection of user defined query execution results | Link |
application/vnd.onkey.translationset+json |
Response contains a collection of translations keys | Link |
Status Codes
Each REST API request returns a success or error HTTP status code:
| Code | Description |
|---|---|
200 OK |
The request succeeded |
201 Created |
A POST method successfully created a resource. |
202 Accepted |
A request was successfully registered or scheduled for asynchronous execution. |
204 No Content |
The server successfully executed the method but returns no response body |
400 Bad Request |
The server could not understand the request. Indicates that the data is not in the expected data format or that a required field is not available. |
401 Unauthorized |
The request requires authentication and the caller did not provide valid credentials. |
403 Forbidden |
The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct permissions to view an Asset. |
404 Not Found |
The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key. |
409 Conflict |
The server cannot execute the request operation due to conflicts such as multiple simultaneous updates being issued by different clients. |
415 Unsupported Media Type |
The API cannot process the media type of the request payload. |
500 Internal Server Error |
A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. |
503 Service Unavailable |
The server cannot handle the request for a service due to temporary maintenance or due to the tenant not being available. |
Error Responses
The On Key API returns any error, warning or information message responses using the application/vnd.onkey.notification+json content type. Read more about the response format here.