Standards
The standards of Isometric APIs
Versioning
This API will be safely versioned using root path versioning, in the format /v{major}
. For example, /registry/v0/supplier
.
Compatibility
We won’t make breaking changes to existing API services or endpoints for API versions higher than v0
. If breaking changes are necessary, we’ll release a new major version.
We may deprecate APIs that have been replaced by a newer version. When doing so, we will expect
integrated partners to manage a transition to new resources within the deprecation timeline of old ones.
We will make the following sort of changes we do not consider to be breaking:
- Adding new properties to existing API responses
- Reordering properties in existing API responses
- Adding optional query parameters to API endpoints
It is important that clients are built to be robust to these changes.
Authentication
Most API requests will need to authenticate against the Isometric API in two ways simultaneously:
- By passing a client secret in the
X-Client-Secret
header to identify the system integrating with the API. - By passing an access token in the
Authorization
header to authenticate as a specific organisation, in order to gain access to its private data.
Client Authentication
Every API call to Isometric must include a client secret identifying the client application.
This client secret is tied to a particular environment - sandbox or production. A client secret can be obtained by contacting Isometric directly. Client secrets should be treated as highly sensitive, kept secret and stored accordingly.
The client secret should be submitted on every API request via the X-Client-Secret
header. For example X-Client-Secret: uPrO...wxAh
.
Organization Authentication
In addition, a large number of API requests will require an access token in order the caller to identify themselves and act as a specific Organization.
To authenticate as an Organization you will need to submit a JWT bearer access token via the Authorization
header. For example: Authorization: Bearer eyJh...sw5c
.
This access token can be obtained by contacting Isometric directly. If you are going to be acting on behalf of other Organizations, they will need to request the access token from us and pass them securely to you.
Access token should be treated as highly sensitive, kept secret and stored accordingly.
Access tokens are scoped to a single Organization - so if you are acting on behalf of multiple particular organizations, you will need to submit the appropriate access token on each request.
Access tokens have a TTL of 1 year from generation. When you are approaching expiry, a new token will need to be generated and Isometric will guide you through rotating your current access token which will cease to work post-expiry.
If for whatever reason you suspect your access token is compromised, notify Isometric as soon as possible and we will provide a new access token and invalidate the old one.
Pagination
Our API is based on the Relay pagination spec. Paginated endpoints
will return a PaginatedListResource
which contains:
page_info
- Containing information regarding pagination cursors and the total number of entities.nodes
- Each node is a paginated entity.total_count
- The total size of the list across all pages.
Pagination Parameters
Paginated endpoints also accepted a standard set of query parameters:
last
- An integer number of items to retrieve before the item represented by the cursor passed in thebefore
parameter. Defaults to 10 with a maximum value of 50.before
- An opaque cursor representing the first item in the previously requested page to select items ordered before it. Submit the previously requested page’sstart_cursor
here when paginated backwards.first
- An integer number of items to retrieve after the item represented by the cursor passed in theafter
parameter. Defaults to 10 with a maximum value of 50.after
- An opaque cursor representing the last item in the previously requested page to select items ordered after it. Submit the previously requested page’send_cursor
here when paginated forwards.
For example, querying /registry/v0/beneficiaries
will return a PaginatedListResource
of the first page of 10 items:
{
"page_info": {
"has_previous_page": false,
"start_cursor": ...,
"has_next_page": true,
"end_cursor": "mpG5kcuoFBYtlH",
},
"nodes": [{
"id": "org_12345iso678",
"name": "My Org",
...
}],
"total_count": 100
}
Then querying /registry/v0/beneficiaries?first=15&after=mpG5kcuoFBYtlH
will return a PaginatedListResource
of the next 15 items.
Dates
Datetime fields in the APIs conform to the ISO 8601 date and time format in UTC. For example: 2024-01-22T11:56:48.520641Z
.
Country Codes
Countries are identified in the APIs via ISO 3166-1 Alpha-3 codes. For example: GBR
and USA
Was this page helpful?