Standards

​

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 endpoints
• Adding optional query parameters to API endpoints
• Adding new properties to existing API responses
• Reordering properties in existing API responses

It is important that clients are built to be robust to these changes.

​

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 the before 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’s start_cursor here when paginated backwards.
• first - An integer number of items to retrieve after the item represented by the cursor passed in the after 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’s end_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.