API HTTP standards



HTTP Methods

The API supports 5 HTTP methods for interacting with resources:

  • GET - Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they are read-only.
  • POST - Use a POST request to create new resources. For example, make a POST request to the user's endpoint where the body of your request JSON is a new user.
  • PATCH - Make a PATCH request to update a resource. With PATCH requests, you only need to provide the data you want to change.
  • PUT - Use a PUT request to create or update a resource.
  • DELETE - Use a DELETE request to remove existing resources. For example, make a DELETE request to the user's endpoint to unsubscribe the user from the system.

Making requests

The EADFactory API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PATCH requests require a valid JSON object for the body. Thus, All requests should supply the Accept: application/json header. POST requests must specify the Content-Type: application/json header. Response bodies are as well JSON encoded.

Base-paths

Every request is built as host + manager prefix + the path from the OpenAPI contract. Each of the four managers has its own prefix; the host is the one we issued your credentials for.

Do not add /api to the base-path. The paths in every contract already begin with /api/. If you append it yourself you get /digital-trust/api/api/v1/..., which does not resolve.

base-path                          contract path                    request URL
https://{host}/digital-trust  +  /api/v1/private/case-files  =  https://{host}/digital-trust/api/v1/private/case-files

Manager prefixes

Manager Prefix OpenAPI contract (no credentials needed)
Evidence Manager /digital-trust {host}/swagger/digital-trust-api-1.0.yml
Notification Manager /notifications {host}/swagger/notifications-api-1.0.yml
Chat Manager /chat-bot-manager {host}/swagger/chat-manager-bot-api-1.0.yml
Signature Manager /signature-manager {host}/swagger/signature-manager-1.0.yml

Those contract files are public: you can download all four before you have any credentials, and generate a client from them.

Your host

The host is specific to your tenant and environment, and we give it to you together with your credentials. You can also always recover it from the token itself: the aud claim of any token we issue you is the host it is valid for. See What the token contains.

Do not assume the host of one environment from another, and do not reuse a colleague's: a token presented to the wrong host does not fail with a helpful message, it fails with a 404.

Why a correct URL can still answer 404

The gateway will not forward a request it cannot match, and what it returns in that case looks like a wrong address:

HTTP/1.1 404 Not Found
{"message":"no Route matched with those values","request_id":"..."}

That 404 almost never means the path is wrong. It has six causes, and the response is identical for all of them:

  1. No Authorization header at all.
  2. The header is present but without the Bearer prefix.
  3. The token was issued for a different environment.
  4. Your tenant is not enabled for that manager in that environment. Ask us to enable it.
  5. That manager is not served on the host you called.
  6. The base-path was built with a duplicated /api.

A browser cannot be one of your clients: the CORS preflight never carries Authorization, so the gateway answers 404 to it. This API is server to server.


Parameters

There are 3 main categories of parameters for each endpoint in the EADFactory API: path, request body, and response body. This section offers an overview of the 3.

Path parameters

In an API url, we include resource names and unique identifiers to help you figure out how to structure your requests. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your EADFactory client account. Let’s look at an example:

'https://{host}/digital-trust/api/v1/private/case-files/{caseFileId}/evidence-groups/{evidenceGroupId}/evidences/{evidenceId}'

In this request example, there is one primary resource case-files, a secondary one evidence-groups and tertiary one evidences. There are also 3 resource identifiers that you need to replace with real values of your EADFactory account: caseFileId, evidenceGroupId and evidenceId.

Request body parameters

For PATCH, and POST requests, you may need to include a request body in JSON format. The case file operations docs, the evidence group operations docs, the evidence operations docs and the report operations docs show you all the available request parameters for each endpoint, including the required fields.

Response body parameters

Every API call response includes headers and an optional JSON-formatted body.


HTTP Status Codes

In this section you can rapidly review all the HTTP status codes you can get with the EADFactory API so that you can get back to work as fast as possible.

Success codes

Http Status Error code Description
200 OK Standard response for successful HTTP requests. The actual response will depend on the request method used.
201 Created A new resource has been created.
202 Accepted The process has not finished e.g. user creation. Usually when the process is asynchronous.

Client errors codes

Http Status Error code Description
400 Bad Request The request cannot be fulfilled due to bad syntax. Usually used for request fields validations.
401 Unauthorized The token reached the service but was not accepted: typically expired, or issued by a different environment. A request with no token at all does not reach the service: the gateway answers 404, see Base-paths.
403 Forbidden If authentication credentials were provided in the request, the server considers them insufficient to grant access.
404 Not Found The origin server did not find a current representation for the target resource. It is also what the gateway returns for any authentication problem. If the body reads no Route matched with those values the request never reached the service, and the cause is one of the six listed under Base-paths.
409 Conflict The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict.
406 Not Acceptable The requested representation cannot be produced. In practice, a missing or wrong Accept header.
422 Unprocessable Entity The body was syntactically valid but a business rule rejected it. The actionable part is the marker between hashes inside the message, see Error responses.

Server error codes

Http Status Error code Description
500 Internal Server Error A generic error message, given when no more specific message is suitable. Should not be thrown programmatically.
503 Service Unavailable The server is currently down and unable to handle the request

Error responses

An error can be produced by four different layers, and each one uses a different envelope. Write your error handling against all of them, or against none: a client that assumes a single shape will break on the first error it did not expect.

The five shapes

1. Field validation. Evidence Manager. errors is an object, and validation maps the rule to the offending fields.

{"errors":{"code":"validation","validation":{"not_empty":["testimony"]}}}

2. Business rule, map dialect. Evidence Manager. errors is an object and the actionable part is the marker between hashes, inside message.

{"errors":{"code":"entity_already_exists","message":"... #CASE_FILE_ALREADY_EXISTS_BY_ID#"}}

3. Business rule, list dialect. Notification Manager and Signature Manager. errors is an array, and here the marker lives in detail, with a separate code field.

{"errors":[{"status":400,"detail":"...","message":"...","code":"TENANT_IS_NOT_VALID"}]}

4. Framework default (HAL). Produced by the runtime when a request never reaches application code, for example an unknown path inside a manager.

{"message":"Not Found","_links":{"self":{"href":"/api/v1/...","templated":false}}}

Do not parse the HAL message as text. For some failures it carries internal class names. Treat it as opaque and rely on the HTTP status.

5. Gateway. The request never reached any service. Recognisable by request_id, and it never contains a marker between hashes.

{"message":"no Route matched with those values","request_id":"..."}

How to read one

The actionable value is the marker between hashes, such as #CASE_FILE_ALREADY_EXISTS_BY_ID#. It is stable across releases; the surrounding prose is not, and neither is the HTTP status in every case.

Where to find it depends on the dialect: in the map dialect it is inside message; in the list dialect, inside detail. So errors[0].code, the natural thing to write after seeing shape 3, throws on shapes 1 and 2, where errors is not an array.

A single defensive accessor covers all five: check whether errors is an array or an object, fall back to the top-level message, and extract the marker with /#([A-Z0-9_]+)#/.