Overview

The Socotra API exposes all platform functionality and follows common conventions for resource interaction. Endpoints and types are described in a uniform manner on each API page.

While it is possible to use the OpenAPI Definition File as a source for auto-generated API clients, we recommend using the file primarily as a parsable, comprehensive index of the entire API surface. You may need to tweak clients automatically generated from the OpenAPI definition.

List Endpoints

List endpoints, such as the Fetch Multiple Accounts API endpoint, follow consistent pagination conventions, allowing you to specify the number of items per page and offsets to navigate the list.

When fetching an entire collection from a list endpoint, you should continue fetching pages until the listComplete property returns true. Due to features such as Data Access Controls and various other factors, the platform may not provide the requester with all possible items in the collection. Therefore, listComplete: false should not be interpreted to mean that the requester can always obtain more items on subsequent fetches. The platform will consistently provide listComplete: true as a signal to the requester that no additional items can be obtained beyond that page (offset and count).

Here is a JavaScript example of a looping technique that retrieves a complete collection from a list endpoint:

// Omitting auth for simplicity
const API_URL = "https://...";
const tenantLocator = "abc...";

let offset = 0;
const count = 100;    // Page size
const allItems = [];

let listCompleted = false;

do {
    const url = new URL(`/policy/${tenantLocator}/accounts/list`, API_URL);
    url.search = new URLSearchParams({
        count,
        offset,
        extended: true,
    });

    const response = await fetch(url);

    if (!response.ok) {
        throw new Error(`Request failed: ${response.status}`);
    }

    const page = await response.json();

    allItems.push(...page.items);
    listCompleted = page.listCompleted;
    offset += count;
} while (!listCompleted);

Additional Notes

• When an endpoint request completes successfully, it will return a 200 status, even if the response is the platform informing you of some kind of error. In this fashion, we distinguish between the platform domain and any abnormal results concerning HTTP requests themselves.

• By default, any collection in a request is optional unless particular usage necessitates the provision of a collection (in which case, the platform will return a response to indicate that). If a collection is listed as required but you have no apparent need to provide any values for the collection, it is always safe to provide an empty collection, which the platform will ignore.