Developer’s Guide

Introduction

RIC One API provides education application developers with an easy and consistent way to access class roster data, while enabling districts to retain complete control of privacy and security for their students and staff. RIC One is available to all RIC member district in the state of New York. Data is partitioned into 12 regional data providers hosted within the private cloud of the Regional Information Centers.

Authentication

RIC One API supports authenticating using the following methods:

• Basic
• OAuth 2.0

RIC One API separates authentication and data access. There is a single authentication endpoint that all apps initially connect to using credentials provided during the onboarding process. Applications login using the username and password provided during the onboarding process to obtain a token and list of regional data providers (endpoints) to which they have been granted access. If your app is used in multiple RICs, you will receive a list containing multiple endpoints. If your app is used only within a single RIC, you will only see a single endpoint in the results of the call to the login service.

Acquire a token

You can retrieve your access token by logging in to https://auth.ricone.org/login. There is a set of test and demo logins available to use for self-testing. By default, tokens expire after 60 minutes and must be refreshed.

Example OAuth Response

In the example below an account with the username of “DemoApp” has logged in and received a JSON payload. This response contains both a token and an array of endpoints. The token received will be used to authenticate at the specified regional provider endpoint. Each endpoint contains information about the provider where the data is located for each of the districts associated to the authenticated application.

Authenticating with your token

Making authenticated calls to the API can be achieved by adding the bearer token to the "Authorization" header. Example:

API Responses

RIC One API offers a variety of responses. You can use Response Headers to gain additional insight into your request as well as HTTP status codes to further explain what state your request was when completed. Content-Type fully supports JSON and XML responses, though the default type is XML.

Response Headers

HTTP GET Status Response

Developer Resources

Developer Sandbox

The Developer Sandbox is an area that allows application developers a place to familiarize themselves with the data accessible through RIC One API. The sandbox includes an API Explorer https://sandbox.ricone.org and access to a complete sample dataset represented in the SIF xPress data model. This will allow developers to perform GET operations and learn the layout of the RIC One API data models.

API Libraries

We provide client libraries for .NET and Java that you may use as a reference implementation or incorporate directly into your product code.

• .NET Documentation
• Java Documentation

Data API

Data Models

RIC One API is implemented on a feature rich, open source toolset called the Common Framework. This technology is used widely in Australia and has excellent scaling characteristics. It can easily support multiple API output models. Our featured API is known as xPress Roster. In the future we may support additional standards based on market demand.

xPress Roster API

The RIC One project team developed a standards-based API that has been adopted by the Access For Learning community (A4L, formerly known as the SIF Association) as a part of its North American national standard. You can view the API explorer here: (https://sandbox.ricone.org/xPress/)

The main design goal for the xPress Roster API was to provide an easy to use on-the-wire representation of rosters and necessary related resources. Following is a high level Entity Relationship Diagram that depicts the relationship among the resources.

Since this model is normalized for interoperability and, for the sake of convenience, most commonly used elements are represented in multiple resources. The underlying physical model within the API provider data store is responsible for maintaining integrity.

Reference Identifiers

In order maintain anonymity and uniqueness, RIC One API assigns each record with a unique reference identifier (refId) or GUID. This is based on Version 4 of the Universally Unique Identifier.

What does a refId look like?

Use of RefIds

Within RIC One API refIds are used for consistency within the system. The refIds are used as a standardized way of filtering data objects to the individual record. For example, if you want to see the full record for an individual student you would request

Or the school enrollment of a particular student:

It is recommended that when developing against the Data API, refIds are used as primary key. However natural (SIS) keys are supported for certain resources and service paths.

Student Identifiers (Local)

In addition to refIds, student resources within RIC One API also generally contain the SIS provided primary key, also known as localId. This identifier can be referenced via

• xStudents.localId

These natural SIS identifiers may be used in place of the refId to query a specific resource. It is generally recommended that refId is used since it is more durable (SIS identifiers can and do change on occasion).

Staff Identifiers (Local)

As with Student Identifiers, staff within RIC One API have additional identifiers associated to their record. These include:

• xStaffs.localId

Scoping Requests for Data
There are multiple strategies you may take to scope requests for data depending on your application's tenancy implementation and data model. Two of the main approaches are to scope by Provider or by District. If you look at the service paths in the table below you can see how you might do this. If you wanted to retrieve all Schools regardless of which district they were a part of you could simply call:

 If you wanted to retrieve a set of Schools based on a district you might do:

When taking the “By District” approach you will first have to retrieve a list of xLeas and then iterate over them. This approach will require an additional call to the API, but it will increase the overall performance when returning data about any particular object.

See API Library for documentation on how to implement this.

Example:

Service Paths

RIC One API offers many ways in which you can retrieve your data. Whether it be through returning all records for a particular object, a single record, or all records by association.

Service Paths by Data Model

Objects on the right are returned using the object on the left and it’s Reference Identifier.

Using Lists

To make the model self documenting multi-valued items are split into two parts: a “primary” and “other” structure. The primary structure can be depended on to provide the main value of interest to most clients. For example, when you see “name” and “otherNames” you would use the “name” field as the primary name for the particular object and, unless your application needs the other names, would ignore those fields. This pattern applies to all items that are potentially multi-valued. This allows us to provide you the best of both worlds: if you only need the primary item from the list just code to look for that primary item; if your application needs additional details, the “other” structure can provide them.

For xStudents the lists include

• name and otherNames
• LocalID and otherId’s
• phoneNumber and otherPhoneNumbers
• email and otherEmail
• phoneNumber
• otherPhoneNumbers
• enrollment.lea or otherEnrollments.lea

Example of “ids”/”otherIds” and “phoneNumber”/“otherPhoneNumbers” construct in xSchool:

Field Level Access Controls

When using the API your application will only see the subset of the fields your applications is approved for. This is decided during the onboarding process between the district, vendor, and a RIC One Onboarding Technician.

Paging

Requests to the Data API can return large amounts of data. To increase performance, the use of the API's paging features is recommended.

navigationPage

The navigationPage attribute describes your current location in paging. Starts at position 0.

navigationPageSize

The navigationPageSize attribute allows you determine the number of results requested per page.

Example Paging Request

The example below shows how you would append these attributes to a service path.

Content Types/Serialization Format

By default, the Data API returns results in XML format but supports returning data in JSON. For compatibility with your application, the return type can be specified.

Example XML Call

Example JSON Call

School Year

By default, the Data API will return the latest school year currently available. If previous years data is needed, a request header or query parameter MUST be added to your REST request.

"Changes Since"

The “Changes Since” mechanism allows an application to request data that has changed since a given point. The RIC One opaque marker uses an ISO8601 timestamp that indicates a point since the last changes have been requested.

Note: Applications which choose to use the natural ids as keys in their applications for primary key will not be able to support "Changes Since" fully. Delete events contain only the refId of the object and applications will need to maintain the linking of refIds to natural identifiers (e.g. student.localId, staff.localId)