Operations

Interop Data APIs support two operations:

• List operations such as listOrgs and listStudentSchoolMemberships retrieve all data objects for a given topic or relationship
• Find operations like findStudent retrieve a single data object by Data Sync ID ($sys.id)

📘

Creating, Updating and Deleting Data

The Interop Data APIs can be used to read data from a repository but cannot directly create, update or delete data. This is because all changes made to a repository must be performed via the Ingestions API. See the Ingestions API for details.

List

A List operation is a query for all data objects in a topic or all data objects that satisfy a relationship. For example, you can query for all Orgs, Persons, or Sections or you can query for all Students that have a membership in a specific School or Section.

List operations are always paged. You specify the page number and size as query parameters: page is the zero-based page number and is required; page_size is the number of data objects to return per page. It is optional and defaults to 2000.

The result of a List operation is a JSON object that contains two keys: data and paging. The data key is an array of data objects that satisfy the query. The paging key is a JSON object that provides additional paging information. paging.next is a URL to the next page or null if there are no additional pages. To consume all data objects, start with page 0 and continue making requests for subsequent pages until paging.next is null.

Example

The following example illustrates listing all Person objects.

1. Request the first page of 2000 objects:

GET /v2/interop/data/rostering/orgs?page=0 HTTP/1.1

{
  "data": [ ... ],
  "paging": {
    "next": "https://api.us2.kimonocloud.com/v2/interop/data/rostering/orgs?page=1&page_size=2000"
  }
}

2. Continue requesting the next page of data until paging.next is null.

GET /v2/interop/data/rostering/orgs?page=1&page_size=2000 HTTP/1.1

{
  "data": [ ... ],
  "paging": {
    "next": null
  }
}

Find

A Find operation is a query for a specific data object by Data Sync ID ($sys.id).

Find operations are not paged. The result of a Find operation is a JSON data object with a single data array comprised of the requested data object. If the requested object is not found a 404 Not Found response is returned instead.

Example

Find a Person that exists in the repository:

GET /v2/interop/data/rostering/persons/9e165c9f-d0e1-47a2-8b68-0e5669992637 HTTP/1.1

{
  "data": [{
    "$sys": {
      "id": "9e165c9f-d0e1-47a2-8b68-0e5669992637",
      "label": "Johnson, Gary",
      "person_type": "Student"
    },
    name: {
      "first": "Gary",
      "middle": "",
      "last": "Johnson",
    },
    ...
  }]
}

Request a Person that does not exist in the repository:

GET /v2/interop/data/rostering/persons/9e165c9f-d0e1-47a2-8b68-0e5669992637 HTTP/1.1

404 Not Found