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