> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isometric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Standards

> API versioning, pagination standards, and data format conventions including ISO 8601 dates and ISO 3166-1 country codes

## 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](https://relay.dev/docs/tutorial/connections-pagination/) 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:

```json theme={null}
{
    "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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) codes. For example: `GBR` and `USA`.