RIC One API .NET Client Library

Introduction

Requirements and Dependencies

Client Library Classes

Authenticator Class

Decoded Token Class

XPress Class

xPress Requests

xPress Data Methods

Returning Lea or School Data Using BEDS Code or Local Id

Example Usage

Account Username/Password Provisioning

Changes Since

GetLastPage

How To

Authenticate

OAuth

Retrieve Endpoints

All Endpoints

Single Endpoint

Accessing xPress Objects

Retrieving Multiple Objects for List of Objects

Return multiple xLeas

Retrieve a Single Object

Return a single xLea

Adding Paging to an Object

Variable

GetLastPage Method

Example

RIC One API Client Library Project

Introduction

The RIC One .NET Client Library was developed using .NET 4 and RestSharp (http://restsharp.org/).

Requirements and Dependencies

  • .NET 4+
  • RICOne Client Library
  • Json.NET v8.0.3
  • JWT v1.3.4
  • RestSharp for .NET 4

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
clientId
clientSecret

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.

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
schoolYear

List<XLeaType>

Returns all Leas.

xLeas

GetXLeas()

opaqueMarker

navigationPage

navigationPageSize

List<XLeaType>

Returns  all Lea value changes from a given point.

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

GetXSchools()

opaqueMarker

navigationPage

navigationPageSize

List<XSchoolType>

Returns  all School value changes from a given point.

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

GetXCalendars()

opaqueMarker

navigationPage

navigationPageSize

List<XCalendarType>

Returns  all Calendar value changes from a given point.

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

GetXCourses()

opaqueMarker

navigationPage

navigationPageSize

List<XCourseType>

Returns  all Course value changes from a given point.

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

GetXRosters()

opaqueMarker

navigationPage

navigationPageSize

List<XRosterType>

Returns  all Roster value changes from a given point.

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

GetXStaffs()

opaqueMarker

navigationPage

navigationPageSize

List<XStaffType>

Returns  all Staff value changes from a given point.

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

GetXStudents()

opaqueMarker

navigationPage

navigationPageSize

List<XStudentType>

Returns  all Student value changes from a given point.

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

getXContacts()

opaqueMarker

navigationPage

navigationPageSize

List<XContactType>

Returns  all Contact value changes from a given point.

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 this features, please follow this link.

API Service Path

Method

Parameters

Return Type

Translation

xSchools/{refId}/xStaffs?createUsers=true

CreateXStaffUsers()

refId

List<XStaffType>

Create Staff usernames and passwords for a specific  School by refId.

xSchools/{refId}/xStaffs?deleteUsers=true

DeleteXStaffUsers()

refId

List<XStaffType>

Delete generated Staff passwords for a specific School by refId.

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

List<XStudentType>

Create Student usernames and passwords for a specific  School by refId.

xSchools/{refId}/xStudents?deleteUsers=true

DeleteXStudentUsers()

refId

List<XStudentType>

Delete generated Student passwords for a specific School by refId.

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. More information can be found under Changes Since in the API Developer’s Guide.

The following methods are supported in the client libraries:

Methods

GetXLeas()

GetXSchools()

GetXCalendars()

GetXCourses()

GetXRosters()

GetXStaffs()

GetXStudents()

GetXContacts()

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

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";
const string clientId= "YOUR USERNAME";
const string clientSecret = "YOUR PASSWORD";

Authenticator auth = Authenticator.Instance;
auth.Authenticate(authUrl, clientId, clientSecret);

Retrieve Endpoints

All Endpoints

foreach (Endpoint e in auth.GetEndpoints())
{
   
//Code to pass url to access data api
}

Single Endpoint

string providerId = "sandbox"

foreach (Endpoint e in auth.GetEndpoints(providerId))
{
   
//Code to pass url to access data api
}

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);

foreach (XLeaType l in xPress.GetXLeas().Data)
{
   
//Code that returns values from the XLeaType object
}

Retrieve a Single Object

Return a single xLea

XPress xPress = new XPress(e.href);

XLeaType l = xPress.GetXLea(refId).Data;

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;
static int navigationPageSize = 5;

XPress xPress =
new XPress(e.href);

foreach(XRosterType r in xPress.GetXRosters(navigationPage, navigationPageSize).Data)
{
        
//Code that returns values from the XRosterType object                    
}

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;

XPress xPress =
new XPress(e.href);

for (int i = 1; i <= xPress.GetLastPage(ServicePath.GetXRosters, navigationPageSize); i++ )
{
        
foreach (XRosterType r in xPress.GetXRostersByXLea(i, navigationPageSize).Data)
        {
                
//Code to return xRoster objects
        }
}

 Example

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using RicOneApi.Api;
using RicOneApi.Models.Authentication;
using RicOneApi.Models.XPress;

namespace SampleConsole
{
   
class Program
   {
       
const string authUrl= "AUTH URL";
       
const string clientId= "YOUR USERNAME";
       
const string clientSecret = "YOUR PASSWORD";
       
const string providerId = "sandbox";
       
static int navigationPageSize = 100;

       
static void Main(string[] args)
       {
           Authenticator auth = Authenticator.Instance;
           auth.Authenticate(authUrl, clientId, clientSecret);

           
foreach (Endpoint e in auth.GetEndpoints(providerId))
           {
               XPress xPress =
new XPress(e.href);

               
foreach (XLeaType l in xPress.GetXLeas().Data)
               {
                   
for (int i = 1; i <= ricOne.xPress.GetLastPage(ServicePath.GetXRostersByXLea, l.refId, navigationPageSize); i++ )
                   {
                       
foreach (XRosterType r in xPress.GetXRostersByXLea(l.refId, i, navigationPageSize).Data)
                       {
                           Console.WriteLine(
"courseTitle: " + r.courseTitle);
                           
foreach (XPersonReferenceType p in r.students.studentReference)
                           {
                               Console.WriteLine(
"refId: " + p.refId);
                               Console.WriteLine(
"localId: " + p.localId);
                               Console.WriteLine(
"givenName: " + p.givenName);
                               Console.WriteLine(
"familyName: " + p.familyName);
                           }
                       }
                       Console.WriteLine(
"######## PAGE " + i + " ########");
                   }
                   
               }
           }

           Console.Read();
       }
   }
}

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