RIC One API .NET Client Library
Returning Lea or School Data Using BEDS Code or Local Id
Account Username/Password Provisioning
Retrieving Multiple Objects for List of Objects
RIC One API Client Library Project
Introduction
The RIC One .NET Client Library was developed using .NET 4.6 and RestSharp (http://restsharp.org/).
Requirements and Dependencies
- .NET 4.6
- RICOne Client Library
- NewtonSoft.Json 12.0.0.0
- JWT v5.0.0
- RestSharp for .NET 106.6.9.0
Client Library Classes
Authenticator Class
Handles authentication for user to OAuth server. Included methods return user and provider information necessary to access the data API (i.e. token and url).
* Italicized parameters are optional
Class | Method | Parameters | Type | Translation |
Authenticator | ||||
Instance | Authenticator | Singleton instantiation. | ||
Authenticate | authUrl | void | Establish connection to authenticate to OAuth server. | |
GetToken() | String | Returns the token value. | ||
GetEndpoints() | providerId returnAllEndpoints | List<Endpoint> | Returns all endpoints or specific by providerId. | |
GetEndpoint() | providerId | Endpoint | Returns a single endpoint by providerId. |
Decoded Token Class
The DecodedToken class returns the payload data inside an encrypted JWT token. Information available includes application id, iat, exp, and iss.
Class | Parameters | Type | Translation |
DecodedToken | |||
token | String | Decodes provided token and creates DecodedToken object. |
Class | Method | Type | Translation |
DecodedToken | |||
GetDecodedToken() | DecodedToken | Returns applicaiton_id, iss, iat, and exp from decoded JWT token. | |
application_id | String | Returns the application id of a decoded token. | |
iat | long | Returns the time the JWT token was issued at. | |
exp | long | Returns the time the JWT token expired at. | |
iss | String | Returns the issuer of the JWT token. |
XPress Class
This static class defines all xPress data requests to the API. This class contains methods that allow access to the objects in the xPress data model.
xPress Requests
Information about a request is available by calling Data, Header, Message, or StatusCode.
Method | Example | Return Type | Translation |
Data | {Get xPress Data Method}.Data | See: xPress Data Methods | Objects inside the xPress data methods. |
Json | {Get xPress Data Method}.Json | String | String response in JSON format of the xPress data method. |
Xml | {Get xPress Data Method}.Xml | String | String response in XML format of the xPress data method. |
Header | {Get xPress Data Method}.Header | String | Returns the response header of a request. |
Message | {Get xPress Data Method}.Message | String | Returns the response status message of a request. |
StatusCode | {Get xPress Data Method}.StatusCode | Int | Returns the response status code of a request. |
xPress Data Methods
*Italicized parameters are optional
API Service Path | Method | Parameters | Return Type | Translation |
xLeas | GetXLeas() | navigationPage navigationPageSize | List<XLeaType> | Returns all Leas. |
xLeas/{refId} | GetXLea() | refId schoolYear | XLeaType | Returns a single Lea by refId. |
xLeas/{id} | GetXLea() | idType Id schoolYear | XLeaType | Returns a ingle Lea by BEDS code or Local Id. |
xSchools/{refId}/xLeas | GetXLeasByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XLeaType> | Returns Leas associated to a specific School by refId. |
xRosters/{refId}/xLeas | GetXLeasByXRoster() | refId navigationPage navigationPageSize schoolYear | List<XLeaType> | Returns Leas associated to a specific Roster by refId. |
xStaffs/{refId}/xLeas | GetXLeasByXStaff() | refId navigationPage navigationPageSize schoolYear | List<XLeaType> | Returns Leas associated to a specific Staff by refId. |
xStudents/{refId}/xLeas | GetXLeasByXStudent() | refId navigationPage navigationPageSize schoolYear | List<XLeaType> | Returns Leas associated to a specific Student by refId. |
xContacts/{refId}/xLeas | GetXLeasByXContact() | refId navigationPage navigationPageSize schoolYear | List<XLeaType> | Returns Leas associated to a specific Contact by refId. |
xSchools | GetXSchools() | navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns all Schools. |
xSchools/{refId} | GetXSchool() | refId schoolYear | XSchoolType | Returns a single School by refId. |
xSchools/{id} | GetXSchool() | idType Id schoolYear | XSchoolType | Returns a single School by BEDS code or Local Id. |
xLeas/{refId}/xSchools | GetXSchoolsByXLea() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Lea by refId. |
xCalendars/{refId}/xSchools | GetXSchoolsByXCalendar() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Calendar by refId. |
xCourses/{refId}/xSchools | GetXSchoolsByXCourse() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Course by refId. |
xRosters/{refId}/xSchools | GetXSchoolsByXRoster() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Roster by refId. |
xStaffs/{refId}/xSchools | GetXSchoolsByXStaff() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Staff by refId. |
xStudents/{refId}/xSchools | GetXSchoolsByXStudent() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Student by refId. |
xContacts/{refId}/xSchools | GetXSchoolsByXContact() | refId navigationPage navigationPageSize schoolYear | List<XSchoolType> | Returns Schools associated to a specific Contact by refId. |
xCalendars | GetXCalendars() | navigationPage navigationPageSize schoolYear | List<XCalendarType> | Returns all Calendars. |
xCalendars/{refId} | GetXCalendar() | refId schoolYear | XCalendarType | Returns a single Calendar by refId. |
xLeas/{refId}/xCalendars | GetXCalendarssByXLea() | refId navigationPage navigationPageSize schoolYear | List<XCalendarType> | Returns Calendars associated to a specific Lea by refId. |
xSchools/{refId}/xCalendars | GetXCalendarsByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XCalendarType> | Returns Calendars associated to a specific School by refId. |
xCourses | GetXCourses() | navigationPage navigationPageSize schoolYear | List<XCourseType> | Returns all Courses. |
xCourses/{refId} | GetXCourse() | refId schoolYear | XCourseType | Returns a single Course by refId. |
xLeas/{refId}/xCourses | GetXCoursesByXLea() | refId navigationPage navigationPageSize schoolYear | List<XCourseType> | Returns Courses associated to a specific Lea by refId. |
xSchools/{refId}/xCourses | GetXCoursesByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XCourseType> | Returns Courses associated to a specific School by refId. |
xRosters/{refId}/xCourses | GetXCoursesByXRoster() | refId navigationPage navigationPageSize schoolYear | List<XCourseType> | Returns Courses associated to a specific Roster by refId. |
xRosters | GetXRosters() | navigationPage navigationPageSize schoolYear | List<XRosterType> | Returns all Rosters. |
xRosters/{refId} | GetXRoster() | refId schoolYear | XRosterType | Returns a single Roster by refId. |
xLeas/{refId}/xRosters | GetXRostersByXLea() | refId navigationPage navigationPageSize schoolYear | List<XRosterType> | Returns Rosters associated to a specific Lea by refId. |
xSchools/{refId}/xRosters | GetXRostersByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XRosterType> | Returns Rosters associated to a specific School by refId. |
xCourses/{refId}/xRosters | GetXRostersByXCourse() | refId navigationPage navigationPageSize schoolYear | List<XRosterType> | Returns Rosters associated to a specific Course by refId. |
xStaffs/{refId}/xRosters | GetXRostersByXStaff() | refId navigationPage navigationPageSize schoolYear | List<XRosterType> | Returns Sections associated to a specific Staff by refId. |
xStudents/{refId}/xRosters | GetXRostersByXStudent() | refId navigationPage navigationPageSize schoolYear | List<XRosterType> | Returns Rosters associated to a specific Student by refId. |
xStaffs | GetXStaffs() | navigationPage navigationPageSize schoolYear | List<XStaffType> | Returns all Staff. |
xStaffs/{refId} | GetXStaff() | refId schoolYear | XStaffType | Returns single Staff by refId. |
xStaffs/{id} | GetXStaff() | idType Id schoolYear | XStaffType | Returns a single Staff by state or local id. |
xLeas/{refId}/xStaffs | GetXStaffsByXLea() | refId navigationPage navigationPageSize schoolYear | List<XStaffType> | Returns Staff associated to a specific Lea by refId. |
xSchools/{refId}/xStaffs | GetXStaffsByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XStaffType> | Returns Staff associated to a specific School by refId. |
xCourses/{refId}/xStaffs | GetXStaffsByXCourse() | refId navigationPage navigationPageSize schoolYear | List<XStaffType> | Returns Staff associated to a specific Course by refId. |
xRosters/{refId}/xStaffs | GetXStaffsByXRoster() | refId navigationPage navigationPageSize schoolYear | List<XStaffType> | Returns Staff associated to a specific Roster by refId. |
xStudents/{refId}/xStaffs | GetXStaffsByXStudent() | refId navigationPage navigationPageSize schoolYear | List<XStaffType> | Returns Staff associated to a specific Student by refId. |
xStudents | GetXStudents() | navigationPage navigationPageSize schoolYear | List<XStudentType> | Returns all Students. |
xStudents/{refId} | GetXStudent() | refId schoolYear | XStudentType | Returns a single Student by refId. |
xStudents/{id} | GetXStudent() | idType Id schoolYear | XStudentType | Returns a single Student by state or local id. |
xLeas/{refId}/xStudents | GetXStudentsByXLea() | refId navigationPage navigationPageSize schoolYear | List<XStudentType> | Returns Students associated to a specific Lea by refId. |
xSchools/{refId}/xStudents | GetXStudentsByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XStudentType> | Returns Students associated to a specific School by refId. |
xRosters/{refId}/xStudents | GetXStudentsByXRoster() | refId navigationPage navigationPageSize schoolYear | List<XStudentType> | Returns Students associated to a specific Roster by refId. |
xStaffs/{refId}/xStudents | GetXStudentsByXStaff() | refId navigationPage navigationPageSize schoolYear | List<XStudentType> | Returns Students associated to a specific Staff by refId. |
xContacts/{refId}/xStudents | GetXStudentsByXContact() | refId navigationPage navigationPageSize schoolYear | List<XStudentType> | Returns Students associated to a specific Contact by refId. |
xContacts | GetXContacts() | navigationPage navigationPageSize schoolYear | List<XContactType> | Returns all Contacts. |
xContacts/{refId} | GetXContact() | refId schoolYear | XContactType | Returns a single Contact by refId. |
xLeas/{refId}/xContacts | GetXContactsByXLea() | refId navigationPage navigationPageSize schoolYear | List<XContactType> | Returns Contacts associated to a specific Lea by refId. |
xSchools/{refId}/xContacts | GetXContactsByXSchool() | refId navigationPage navigationPageSize schoolYear | List<XContactType> | Returns Contacts associated to a specific School by refId. |
xStudents/{refId}/xContacts | GetXContactsByXStudent() | refId navigationPage navigationPageSize schoolYear | List<XContactType> | Returns Contacts associated to a specific Student by refId. |
Returning Lea or School Data Using BEDS Code or Local Id
An alternate Lea or School id can be used when requesting data related to xLeas or xSchools objects. The BEDS code or Local id are acceptable request values in the API. A value for idType must be provided as well as the corresponding id. The following Id Type values are acceptable:
Header | Acceptable Values |
IdType | beds local |
Example Usage
GetXLea("beds", "99999999") |
Account Username/Password Provisioning
For more information about these features, please follow this link.
API Service Path | Method | Parameters | Return Type | Translation | Notes |
xSchools/{refId}/xStaffs?createUsers=true | CreateXStaffUsers() | refId | void | Create Staff usernames and passwords for a specific School by refId. | Deprecated as of 1.7.0. |
xSchools/{refId}/xStaffs?deleteUsers=true | DeleteXStaffUsers() | refId | void | Delete generated Staff passwords for a specific School by refId. | Deprecated as of 1.7.0. |
xSchools/{refId}/xStaffs?deleteUsers=true&usernames=true | DeleteXStaffUsernamesPasswords() | refId | void | Delete generated Staff usernames and passwords for a specific School by refId. | Deprecated as of 1.7.0. |
xSchools/{refId}/xStaffs?getUsers=true | GetXStaffUsers() | refId navigationPage navigationPageSize | List<XStaffType> | Return generated Staff usernames and passwords for a specific School by refId. | |
xSchools/{refId}/xStudents?createUsers=true | CreateXStudentUsers() | refId | void | Create Student usernames and passwords for a specific School by refId. | Deprecated as of 1.7.0. |
xSchools/{refId}/xStudents?deleteUsers=true | DeleteXStudentUsers() | refId | void | Delete generated Student passwords for a specific School by refId. | Deprecated as of 1.7.0. |
xSchools/{refId}/xStudents?deleteUsers=true&usernames=true | DeleteXStudentUsernamesPasswords() | refId | void | Delete generated Student usernames and passwords for a specific School by refId. | Deprecated as of 1.7.0. |
xSchools/{refId}/xStudents?getUsers=true | GetXStudentUsers() | refId navigationPage navigationPageSize | List<XStudentType> | Return generated Student usernames and passwords for a specific School by refId. |
Changes Since
Allows data to be requested that has changed since a given time. This is denoted by the use of the opaqueMarker parameter in each supported method. More information on this feature can be found under Changes Since in the API Developer s Guide.
GetLastPage
Is an overloaded method that is part of the XPress class. It uses enumerator values to specify the xPress data method to be called when requesting the max page value for an object. This value is used for the navigationPage parameter.
* Italicized parameters are optional
Method | Parameters | Return Type | Translation |
GetLastPage() | servicePath navigationPageSize refId opaqueMarker | int | Max page value for specified service path object. |
As noted above, an enumerator is used to handle the object call to determine page size. An enumerator is defined for each of the methods listed under the xPress Data Methods heading above. A call to an enumerator will follow the pattern below:
ServicePath.{xPress Data Method} |
How To
Authenticate
OAuth
Create a new Authenticator object and pass your username and password.
const string authUrl = "AUTH URL"; |
Retrieve Endpoints
All Endpoints
foreach (Endpoint e in auth.GetEndpoints()) |
Single Endpoint
string providerId = "sandbox" |
Accessing xPress Objects
Below are examples of how to interact with
Retrieving Multiple Objects for List of Objects
Return multiple xLeas
XPress xPress = new XPress(e.href); |
Retrieve a Single Object
Return a single xLea
XPress xPress = new XPress(e.href); |
Adding Paging to an Object
Variable
Paging is generally used to limit the returns for testing purposes. Below is a basic example that will return xRosters from page 1 with a return of 5 records.
static int navigationPage = 1; |
GetLastPage Method
The data API has the ability to return the last or max page value of an object that is provided paging parameters. Specifying a page size (navigationPageSize) for a request is required to return the max page size. Below is an example of returning the maximum page size (all) with 100 rosters per page.
static int navigationPageSize = 100; |
Example
using System; |
RIC One API Client Library Project
For the client library and an example, download the project from Git.
https://github.com/RIConeorg/API-ClientLibrary-DotNet