REST API v2

About the REST API

The Registry REST API is designed to allow fine grained resource access to the Registry database. In other words, the REST API interfaces align more or less with the objects stored within, and not to "higher level" abstractions. (This may change with subsequent releases.) The REST API is designed for accessing and managing data objects, not the Registry configuration.

The REST API is not optimized for bulk transactions. A better approach for bulk transactions is to use Organizational Identity Sources.

The API is available at https://server/registry/api/v2/.

Authentication

XXX

Adding a New API User

XXX

Object Formats

v2 of the API only supports JSON for request and response payloads. XML is no longer supported. The VOOT API is no longer supported.

Timezones and Timestamps

All times processed (inbound and outbound) via the REST API are in UTC. For more information on timezones, see Understanding Registry Timezones.

Timestamps are returned in YYYY-MM-DDTHH:MM:SS format (with no timezone indicator).

Request Formats

Requests are provided as an object named for the appropriate model, and an object (for Update requests) or a list of objects (for Add requests) holding model specific attributes (excluding metadata and id).

Requests with a JSON body must be sent with a Content-Type header of application/json.

Response Formats

Response Metadata

Each response includes an object called responseMeta with metadata about the response. Response metadata attributes include:

• resource: The name of the resource (or object) being returned
• version: API version, currently "2"

In addition, Response Metadata may include pagination information, documented below.

Record Metadata

Individual records include a meta object with metadata about the record. Record metadata attributes include:

• actor_identifier: The login identifier associated with the last record modification*
• created: The timestamp of the record creation
• deleted: If true, the record is deleted*
• modified: The timestamp of when the record was last modified
• revision: The revision number of this record*
• attribute_id: If set, this is an older revision of the specified record*

*See Changelog Behavior for more information.

Pagination

Pagination is generally available on "index" listings of objects, ie: requests that can return more than one object in a list. Pagination is controlled by appending the following parameters to the query string:

• direction: Controls the direction of the sort of objects, asc (ascending) or desc (descending)
• limit: The maximum number of results to return (per page)
• sort: The field to sort the results on
• page: Number of page to return results for, with 1 being the first page

The following attributes will be returned in the Response Metadata:

• currentPage: The current page of results, which should correspond to the page parameter
• itemsPerPage: The number of objects in this page, which should correspond to the limit parameter
• pageCount: The total number of pages
• startIndex: The index of the first result (out of totalResults) in the current page, starting from 1 (the first result on the first page)
• totalResults: The total number of results

Standard API Operations (CRUD)

Most APIs implement a standard set of CRUD operations, which are documented here. See the documentation for each API (under API Reference, below) for the details of which attributes are supported for each API, as well supplemental API calls or deviations from the standard CRUD set.

Add

Add one or more new objects.

Request Format

Response Format

Example: Add Two New COs

POST /registry/api/v2/cos.json
{
  "Cos": [
    {
      "name": "REST Test",
      "description": "Test REST API v2",
      "status": "Q"
    },
    {
      "name": "REST Test 2",
      "description": "Second Test REST API v2",
      "status": "A"
    }
  ]
}

200 OK
{
  "results": [
    {
      "error": "Entity save failure (status: \"content\")."
    },
    {
      "id": 142
    }
  ]
}

Delete

Remove an object. In most cases, this will execute a "soft" delete, meaning the record is logically deleted but an archived copy remains in the database. See Changelog Behavior for more information.

Request Format

Response Format

Edit

Edit an existing object. Note the old values for the object are archived, see Changelog Behavior for more information.

Request Format

Response Format

Example: Update CO

PUT /registry/api/v2/cos/142.json
{
  "Cos": {
    "name": "REST Test II",
    "description": "Second Test REST API v2",
    "status": "A"
  }
}

200 OK

View (one)

Retrieve an existing object.

Request Format

Response Format

The response format is the same as for View (all) below, but without pagination metadata.

View (all)

Retrieve all existing objects. This request may be modified by API-specific parameters to filter available results.

Request Format

Response Format

For requests that generate response bodies (ie: "View" requests), the format is a responseMeta object holding Response Metadata, followed by a response object named for the model requested. The response object will be a list of data objects, with a unique id field, a set of attributes appropriate for the model, and a meta section with Record Metadata.

Example: Obtain COs, Paginated

GET /registry/api/v2/cos.json?page=2&limit=3

200 OK
{
  "responseMeta": {
    "totalResults": "20",
    "startIndex": "4",
    "itemsPerPage": "3",
    "currentPage": 2,
    "pageCount": 7,
    "resource": "Cos",
    "version": "2"
  },
  "Cos": [
    {
      "id": 1,
      "name": "COmanage",
      "description": "COmanage Registry Internal CO",
      "status": "A",
      "meta": {
        "created": "2011-07-28T21:26:09+00:00",
        "modified": "2011-07-28T21:26:09+00:00",
        "revision": null,
        "deleted": null,
        "actor_identifier": null,
        "co_id": null
      }
    },
    {
      "id": 2,
      "name": "TestCO",
      "description": "Test CO",
      "status": "A",
      "meta": {
        "created": "2011-07-28T21:27:52+00:00",
        "modified": "2018-11-27T00:37:47+00:00",
        "revision": null,
        "deleted": null,
        "actor_identifier": null,
        "co_id": null
      }
    },
    {
      "id": 68,
      "name": "Flat CO",
      "description": "CO with no COUs",
      "status": "A",
      "meta": {
        "created": "2018-06-01T02:39:04+00:00",
        "modified": "2018-06-01T02:39:04+00:00",
        "revision": null,
        "deleted": null,
        "actor_identifier": null,
        "co_id": null
      }
    }
  ]
}

API Reference

*For APIs available prior to Registry v5.0.0, column denotes introduction of API v1. All APIs transitioned to API v2 with Registry v5.0.0.