RIC One API Java Client Library

Introduction

Requirements and Dependencies

Client Library Classes

Authenticator Class

Decoded Token Class

XPress Class

xPress Requests

xPress Data Methods

Returning 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 Java Client Library was developed using Java JDK 7, Spring’s RestTemplate (http://projects.spring.io/spring-framework/).

Requirements and Dependencies

  • Java JDK 7
  • RIC One Client Library
  • Apache Commons
  • Commons-logging-1.2.jar
  • Auth0
  • java-jwt-2.1.0.jar
  • Jackson FasterXML
  • jackson-databind-2.5.4.jar
  • jackson-annotations-2.5.0.jar
  • Jackson-core-2.5.4.jar
  • Joda Time
  • joda-time-2.8.jar
  • Spring Framework
  • spring-beans-4.1.6.RELEASE.jar
  • spring-core-4.1.6.RELEASE.jar
  • spring-web 4.1.6.RELEASE.jar

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). As of version 1.6, the Authenticator and Decoded Token classes are in a separate repository, API-AuthenticationClientLibrary-Java. This jar will be included with future releases of the API-ClientLibrary-Java.

* Italicized parameters are optional

Class

Method

Parameters

Type

Translation

Authenticator

getInstance()

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

getApplication_id()

String

Returns the application id of a decoded token

getIat()

long

Returns the time the JWT token was issued at

getExp()

long

Returns the time the JWT token expired at

getIss()

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 allows access to the objects in the xPress data model.

xPress Requests

Information about a request is available by calling getData, getHeader, getMessage, or getStatusCode.

Method

Example

Return Type

Translation

getData()

{Get xPress Data Method}.getData()

See: xPress Data Methods

Objects inside the xPress data methods

getHeader()

{Get xPress Data Method}.getHeader()

String

Returns the response header of a request

getMessage()

{Get xPress Data Method}.getMessage()

String

Returns the response status message of a request

getStatusCode()

{Get xPress Data Method}.getStatusCode()

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>

All Leas

xLeas

getXLeas()

opaqueMarker

List<XLeaType>

All Leas from a certain point in time

xLeas/{refId}

getXLea()

refId

navigationPage

navigationPageSize

XLeaType

Single Lea by refId

xLeas/{id}

getXLea()

idType

id

XLeaType

Single Lea by BEDS code or Local Id.

xSchools/{refId}/xLeas

getXLeasByXSchool()

refId

navigationPage

navigationPageSize

List<XLeaType>

Returns Leas associated to a specific School by refId

xSchools/{id}/xLeas

getXLeasByXSchool()

idType

id

List<XLeaType>

Leas associated to a specific School by BEDS code or Local Id

xStudents/{refId}/xLeas

getXLeasByXStudent()

refId

navigationPage

navigationPageSize

List<XLeaType>

Returns Leas associated to a specific Student by refId

xContacts/{refId}/xLeas

getXLeasByXContact()

refId

navigationPage

navigationPageSize

List<XLeaType>

Returns Leas associated to a specific Contact by refId

xSchools

getXSchools()

navigationPage

navigationPageSize

List<XSchoolType>

All Schools

xSchools

getXSchools()

opaqueMarker

List<XSchoolType>

All School value changes from a given point

xSchools/{refId}

getXSchool()

refId

navigationPage

navigationPageSize

XSchoolType

Single School by refId

xSchools/{id}

getXSchool()

idType

id

XSchoolType

Single School by BEDS code or Local Id

xLeas/{refId}/xSchools

getXSchoolsByXLea()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Lea by refId

xLeas/{id}/xSchools

getXSchoolsByXLea()

idType

id

List<XSchoolType>

Schools associated to a specific Lea by BEDS code or Local Id

xCalendars/{refId}/xSchools

getXSchoolsByXCalendar()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Calendar by refId

xCourses/{refId}/xSchools

getXSchoolsByXCourse()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Course by refId

xRosters/{refId}/xSchools

getXSchoolsByXRoster()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Roster by refId

xStaffs/{refId}/xSchools

getXSchoolsByXStaff()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Staff by refId

xStudents/{refId}/xSchools

getXSchoolsByXStudent()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Student by refId

xContacts/{refId}/xSchools

getXSchoolsByXContact()

refId

navigationPage

navigationPageSize

List<XSchoolType>

Returns Schools associated to a specific Contact by refId

xCalendars

getXCalendars()

navigationPage

navigationPageSize

List<XCalendarType>

All Calendars

xCalendars

getXCalendars()

opaqueMarker

List<XCalendarType>

All Calendar value changes from a given point

xCalendars/{refId}

getXCalendar()

refId

navigationPage

navigationPageSize

XCalendarType

Single Calendar by refId

xLeas/{refId}/xCalendars

getXCalendarssByXLea()

refId

navigationPage

navigationPageSize

List<XCalendarType>

Calendars associated to a specific Lea by refId

xLeas/{id}/xCalendars

getXCalendarssByXLea()

idType

id

List<XCalendarType>

Calendars associated to a specific Lea by BEDS code or Local Id

xSchools/{refId}/xCalendars

getXCalendarsByXSchool()

refId

navigationPage

navigationPageSize

List<XCalendarType>

Returns Calendars associated to a specific School by refId

xSchools/{id}/xCalendars

getXCalendarsByXSchool()

idType

id

List<XCalendarType>

Calendars associated to a specific School by BEDS code or Local Id

xCourses

getXCourses()

navigationPage

navigationPageSize

List<XCourseType>

All Courses

xCourses

getXCourses()

opaqueMarker

List<XCourseType>

All Course value changes from a given point

xCourses/{refId}

getXCourse()

refId

navigationPage

navigationPageSize

XCourseType

Single Course by refId

xLeas/{refId}/xCourses

getXCoursesByXLea()

refId

navigationPage

navigationPageSize

List<XCourseType>

Returns Courses associated to a specific Lea by refId

xLeas/{id}/xCourses

getXCoursesByXLea()

idType

id

List<XCourseType>

Courses associated to a specific Lea by BEDS code or Local Id

xSchools/{refId}/xCourses

getXCoursesByXSchool()

refId

navigationPage

navigationPageSize

List<XCourseType>

Courses associated to a specific School by refId

xSchools/{id}/xCourses

getXCoursesByXSchool()

idType

id

List<XCourseType>

Courses associated to a specific School by BEDS code or Local Id

xRosters/{refId}/xCourses

getXCoursesByXRoster()

refId

navigationPage

navigationPageSize

List<XCourseType>

Courses associated to a specific Roster by refId

xRosters

getXRosters()

navigationPage

navigationPageSize

List<XRosterType>

All Rosters

xRosters

getXRosters()

opaqueMarker

List<XRosterType>

All Roster value changes from a given point

xRosters/{refId}

getXRoster()

refId

navigationPage

navigationPageSize

XRosterType

Single Roster by refId

xLeas/{refId}/xRosters

getXRostersByXLea()

refId

navigationPage

navigationPageSize

List<XRosterType>

Returns Rosters associated to a specific Lea by refId

xLeas/{id}/xRosters

getXRostersByXLea()

idType

id

List<XRosterType>

Rosters associated to a specific Lea by BEDS code or Local Id

xSchools/{refId}/xRosters

getXRostersByXSchool()

refId

navigationPage

navigationPageSize

List<XRosterType>

Returns Rosters associated to a specific School by refId

xSchools/{id}/xRosters

getXRostersByXSchool()

idType

id

List<XRosterType>

Rosters associated to a specific School by BEDS code or Local Id

xCourses/{refId}/xRosters

getXRostersByXCourse()

refId

navigationPage

navigationPageSize

List<XRosterType>

Returns Rosters associated to a specific Course by refId

xStaffs/{refId}/xRosters

getXRostersByXStaff()

refId

navigationPage

navigationPageSize

List<XRosterType>

Returns Sections associated to a specific Staff by refId

xStudents/{refId}/xRosters

getXRostersByXStudent()

refId

navigationPage

navigationPageSize

List<XRosterType>

Returns Rosters associated to a specific Student by refId

xStaffs

getXStaffs()

navigationPage

navigationPageSize

List<XStaffType>

All Staff

xStaffs

getXStaffs()

opaqueMarker

List<XStaffType>

All Staff value changes from a given point

xStaffs/{refId}

getXStaff()

refId

navigationPage

navigationPageSize

XStaffType

Single Staff by refId

xLeas/{refId}/xStaffs

getXStaffsByXLea()

refId

navigationPage

navigationPageSize

List<XStaffType>

Returns Staff associated to a specific Lea by refId

xLeas/{id}/xStaffs

getXStaffsByXLea()

idType

Id

List<XStaffType>

Staff associated to a specific Lea by BEDS code or Local Id

xSchools/{refId}/xStaffs

getXStaffsByXSchool()

refId

navigationPage

navigationPageSize

List<XStaffType>

Returns Staff associated to a specific School by refId

xSchools/{id}/xStaffs

getXStaffsByXSchool()

idType

id

List<XStaffType>

Staff associated to a specific School by BEDS code or Local Id

xCourses/{refId}/xStaffs

getXStaffsByXCourse()

refId

navigationPage

navigationPageSize

List<XStaffType>

Returns Staff associated to a specific Course by refId

xRosters/{refId}/xStaffs

getXStaffsByXRoster()

refId

navigationPage

navigationPageSize

List<XStaffType>

Returns Staff associated to a specific Roster by refId

xStudents

getXStudents()

navigationPage

navigationPageSize

List<XStudentType>

All Students

xStudents

getXStudents()

opaqueMarker

List<XStudentType>

All Student value changes from a given point

xStudents/{refId}

getXStudent()

refId

navigationPage

navigationPageSize

XStudentType

Single Student by refId

xLeas/{refId}/xStudents

getXStudentsByXLea()

refId

navigationPage

navigationPageSize

List<XStudentType>

Returns Students associated to a specific Lea by refId

xLeas/{id}/xStudents

getXStudentsByXLea()

idType

id

List<XStudentType>

Students associated to a specific Lea by BEDS code or Local Id

xSchools/{refId}/xStudents

getXStudentsByXSchool()

refId

navigationPage

navigationPageSize

List<XStudentType>

Returns Students associated to a specific School by refId

xSchools/{id}/xStudents

getXStudentsByXSchool()

idType

id

List<XStudentType>

Students associated to a specific School by BEDS code or Local Id

xRosters/{refId}/xStudents

getXStudentsByXRoster()

refId

navigationPage

navigationPageSize

List<XStudentType>

Returns Students associated to a specific Roster by refId

xStaffs/{refId}/xStudents

getXStudentsByXStaff()

refId

navigationPage

navigationPageSize

List<XStudentType>

Returns Students associated to a specific Staff by refId

xContacts/{refId}/xStudents

getXStudentsByXContact()

refId

navigationPage

navigationPageSize

List<XStudentType>

Returns Students associated to a specific Contact by refId

xContacts

getXContacts()

navigationPage

navigationPageSize

List<XContactType>

All Contacts

xContacts

getXContacts()

opaqueMarker

List<XContactType>

All Contact value changes from a given point

xContacts/{refId}

getXContact()

refId

navigationPage

navigationPageSize

XContactType

Single Contact by refId

xLeas/{refId}/xContacts

getXContactsByXLea()

refId

navigationPage

navigationPageSize

List<XContactType>

Returns Contacts associated to a specific Lea by refId

xLeas/{id}/xContacts

getXContactsByXLea()

idType

id

List<XContactType>

Contacts associated to a specific Lea by BEDS code or Local Id

xSchools/{refId}/xContacts

getXContactsByXSchool()

refId

navigationPage

navigationPageSize

List<XContactType>

Returns Contacts associated to a specific School by refId

xSchools/{id}/xContacts

getXContactsByXSchool()

idType

id

List<XContactType>

Contacts associated to a specific School by BEDS code or Local Id

xStudents/{refId}/xContacts

getXContactsByXStudent()

refId

navigationPage

navigationPageSize

List<XContactType>

Returns Contacts associated to a specific Student by refId

Returning 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

getXStudentsByXLea("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 give 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(String opaqueMarker)

getXSchools(String opaqueMarker)

getXCalendars(String opaqueMarker)

getXCoursess(String opaqueMarker)

getXRosters(String opaqueMarker)

getXStaffs(String opaqueMarker)

getXStudents(String opaqueMarker)

getXContacts(String opaqueMarker)

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

navigationPageSize

servicePath

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:

XPress.ServicePath.{xPress Data Method}

How To

Authenticate

OAuth

Create a new Authenticator object and pass your username and password.

final static String authUrl = "AUTH URL";

final static String clientId = "YOUR USERNAME";

final static String clientSecret = "YOUR PASSWORD";

Authenticator auth = Authenticator.getInstance();

auth.authenticate(authUrl, clientId, clientSecret);

Retrieve Endpoints

All Endpoints

for(Endpoint e : auth.getEndpoints())

{

    //Code to pass url to access data api

}

Single Endpoint

String providerId = "sandbox"

for(Endpoint e : 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.getHref());

for(XLeaType l : xPress.getXLeas().getData())

{

     //Code that returns values from the XLeaType object

}

Retrieve a Single Object

Return a single xLea

XPress xPress = new XPress(e.getHref());

XLeaType l = xPress.getXLea(refId).getData();

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 final int navigationPage = 1;

static final int navigationPageSize = 5;

XPress xPress = new XPress(e.getHref());

for(XRosterType r : xPress.getXRosters(navigationPage, navigationPageSize).getData())

{

        //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 final int navigationPageSize = 100;

XPress xPress = new XPress(e.getHref());

for(int i = 1; i <= xPress.getLastPage(navigationPageSize, xPress.ServicePath.GETXROSTERS); i++ )

{

        for(XRosterType r : xPress.getXRostersByXLea(i, navigationPageSize).getData())

        {

                //Code to return xRoster objects

        }

}

 Example

import riconeapi.models.authentication.Endpoint;

import riconeapi.models.XPress.XLeaType;

import riconeapi.models.XPress.XPersonReferenceType;

import riconeapi.models.XPress.XRosterType;

public class SampleConsole

{

       static final String authUrl= "AUTH URL";        

       static final String clientId= "YOUR USERNAME";

        static final String clientSecret = "YOUR PASSWORD";

        static final String providerId = "sandbox";

        static final int navigationPageSize = 500;

        public static void main(String[] args)

        {

                Authenticator auth = Authenticator.getInstance();

               auth.authenticate(authUrl, clientId, clientSecret);

        for(Endpoint e : auth.getEndpoints(providerId))

        {

            Xpress xPress = new XPress(e.getHref());

            for(XLeaType l : xPress.getXLeas().getData())

            {

                    for (int i = 1; i <= xPress.getLastPage(navigationPageSize, XPress.ServicePath.GETXROSTERSBYXLEA, l.getRefId()); i++)

                        {

                        for(XRosterType r :xPress.getXRostersByXLea(l.getRefId(), i, navigationPageSize).getData())

                        {

                            System.out.println("courseTitle: " + r.getCourseTitle());

                            for(XPersonReferenceType p : r.getStudents().getStudentReference())

                            {

                                System.out.println("refId: " + p.getRefId());

                                System.out.println("localId: " + p.getLocalId());

                                System.out.println("givenName: " + p.getGivenName());

                                System.out.println("familyName: " + p.getFamilyName());

                            }

        

                        }

                        System.out.println("######## PAGE " + i + " ########");

                        }

            }

        }

     }

}

RIC One API Client Library Project

For the client library and an example, download the project from Git.

https://github.com/RIConeorg/API-ClientLibrary-Java