Understanding the Documentation

This documentation helps you to understand what endpoints can be called to perform various actions within the API.

In general, the the V2 API is a CRUD based RESTful API. For the most part, each resource will have its own group of endpoints which follow the CRUD pattern of Create, Read, Update and Delete (with an additional one for searching or listing multiple records).

This page will help you understand how the documentation is structured.

Resource Schemas

Each group of endpoints can be found on the left side menu. At the start of each page of endpoints is a schema for how that resource is returned from the API. The schema provided is an example schema, and provides a table of definitions for each item in the schema.

Example Schema

{
  "id": 1,
  "foo": "bar",
  "dates": {
    "created_at": "2024-01-01 00:00:00"
  }
}

In the example above, we have the example schema represented in JSON to the right, and a definition table on the left.

The definition table will give you a description of each property of the schema. Each field in the definition table will provide 3 pieces of data:

• The field key
• The field type or types
• A description

The field key will always be highlighted in code tags. To the right of the field key is the field type, or types. Each field will have one or more types, such as int, string, null, object.

If the field type is an object, the description will always contain a child definition list which follows the same structure. Otherwise, the description will give you any additional information you may need to know about that particular field.

Endpoint Definitions

Endpoint definitions allow you to see exactly what URLs to call to perform various actions, what method should be used, definitions of any URI parameters, payload structures, responses, SDK and cURL example calls, errors returned etc.

When implementing an endpoint, the documentation should be used as a source of truth, and the implementation must match the documentation exactly.

Example Endpoint Definitions

Create Resource

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->resources()
  ->create([
    'foo_a' => 'Hello',
    'foo_b' => 'World',
  ]);

{
  "data": {
    "id": 1,
    "foo_a": "bar",
    "foo_b": "world",
    "dates": {
      "created_at": "2024-01-01 00:00:00"
    }
  }
}

In the example definition above, the page will always be split into 2 sections. The left side will give you information about the request, the right side will give you examples of how to make the request, and what to expect as a response.

In requests where a payload is expected, there will be a payload title on the left hand side. This section gives you details about what values to provide in the request and the structure of the request.

It follows the same structure as the resource definition table with an additional piece of information.

When a field is required, a red required flag will be presented to the right of the field key. If this flag is not displayed, the field is considered optional in the request.

When performing create operations, if an optional field is not provided, a default value will be stored. The default value will usually be displayed within the description of the field. When performing update operations, if an optional field is not provided in the request, it will not be updated in the database.

For example, in the request definition above, foo_b is not a required field. If the existing record has a value of foo_b: Space and we provide foo_b: World in the request, this value will be updated to World. If we don't provide foo_b at all in the request, the value will remain as Space in the database.

There may be occasions where a field accepts multiple different data types, such as int | null. This means when provided in the request, the value must be either an integer or null.

So, using the example endpoint above to create a resource, the following requests are both acceptable:

{
  "foo_a": "Hello",
  "foo_b": "World"
}

{
  "foo_a": "Hello"
}

However, these requests would fail:

{
  "foo_b": "World"
}

{
  "foo_a": "Hello"
  "foo_b": null
}