Skip to main content

General guidelines

Errors​

HTML status code responses follow the common pattern:

  • 2xx: Successful responses
  • 4xx: Client error responses
  • 5xx: Server error responses

Most error responses offer additional information for troubleshooting.

Pagination​

Pagination is handled similarly across different resources.

Query parameters​

When retrieving lists of objects (keys, DIDs, credential schemas, and others), optionally pass two different query parameters to control what is returned and how: page and pageSize.

  • Passing a page value returns a specific page of the results. The first page is 0.
  • Passing a pageSize value controls how many items appear on each page. The default value for the Desk API is 30. For the Core API, a value must be specified.

Returned values​

When lists are returned, there are two pagination-related values returned: totalItems and totalPages.

  • The totalItems value is the total number of the associated items.
  • The totalPages value is the total number of pages the list has.

Names​

The following resources require passing a name (as a string) during creation:

  • Keys
  • DIDs
  • Credential schemas
  • Proof schemas

This name provides a reference for admins and users. For any given resource, each name must be unique within any given organization.

Filtering​

Filtering is handled similarly across different resources. Pass query parameters to filter lists.

The following resources can return filterable lists:

  • Keys
  • DIDs
  • Credential schemas
  • Credentials*
  • Proof schemas
  • Proof requests*

Each of these resources can be filtered by:

  • name: all names starting with the string passed are returned
    • this value is not case-sensitive
    • * filters by the name of the respective schema in use
  • exact: indicate which columns should be an exact match
    • the columns which are passable here vary between resources and are described in each method/endpoint description

Some resources provide additional filtering options. These are described in the endpoint reference descriptions.

For the include filter option, supported values are indicated explicitly. If no values are directly specified, no values are supported.

Sorting​

Sorting is handled similarly across different resources. Pass query parameters to sort lists.

There are two sorting values:

  • sort: sort results by a result in the response value. Not all response values are supported. Supported values are listed in each endpoint reference description.
  • sortDirection: order the results by increasing (ASC) or decreasing values (DESC). Supported values:
    • ASC
    • DESC

If no sorting values are provided, createdDate + DESC are used.

If a value is passed for sort, the default direction becomes ASC.

URLs​

The URLs generated by the system (such as when issuing credentials or requesting proofs) are specific to the exchange protocol being used and are typically shared via QR code. Any third-party system utilizing the same exchange protocol can parse the URLs generated by the system.