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.
	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.
	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 opaqueMarker schoolYear	List<XLeaType>	All Leas.
xLeas/{refId}	getXLea()	refId schoolYear	XLeaType	Single Lea by refId.
xLeas/{id}	getXLea()	idType Id schoolYear	XLeaType	Single Lea by BEDS code or Local Id.
xSchools/{refId}/xLeas	getXLeasByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XLeaType>	Returns Leas associated to a specific School by refId.
xStudents/{refId}/xLeas	getXLeasByXStudent()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XLeaType>	Returns Leas associated to a specific Student by refId.
xContacts/{refId}/xLeas	getXLeasByXContact()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XLeaType>	Returns Leas associated to a specific Contact by refId.

xSchools	getXSchools()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	All Schools.
xSchools/{refId}	getXSchool()	refId schoolYear	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 opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Lea by refId.
xCalendars/{refId}/xSchools	getXSchoolsByXCalendar()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Calendar by refId.
xCourses/{refId}/xSchools	getXSchoolsByXCourse()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Course by refId.
xRosters/{refId}/xSchools	getXSchoolsByXRoster()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Roster by refId.
xStaffs/{refId}/xSchools	getXSchoolsByXStaff()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Staff by refId.
xStudents/{refId}/xSchools	getXSchoolsByXStudent()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Student by refId.
xContacts/{refId}/xSchools	getXSchoolsByXContact()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XSchoolType>	Returns Schools associated to a specific Contact by refId.

xCalendars	getXCalendars()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XCalendarType>	All Calendars.
xCalendars/{refId}	getXCalendar()	refId schoolYear	XCalendarType	Single Calendar by refId.
xLeas/{refId}/xCalendars	getXCalendarssByXLea()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XCalendarType>	Calendars associated to a specific Lea by refId.
xSchools/{refId}/xCalendars	getXCalendarsByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XCalendarType>	Returns Calendars associated to a specific School by refId.

xCourses	getXCourses()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XCourseType>	All Courses.
xCourses/{refId}	getXCourse()	refId schoolYear	XCourseType	Single Course by refId.
xLeas/{refId}/xCourses	getXCoursesByXLea()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XCourseType>	Returns Courses associated to a specific Lea by refId.
xSchools/{refId}/xCourses	getXCoursesByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XCourseType>	Courses associated to a specific School by refId.
xRosters/{refId}/xCourses	getXCoursesByXRoster()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XCourseType>	Courses associated to a specific Roster by refId.

xRosters	getXRosters()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XRosterType>	All Rosters.
xRosters/{refId}	getXRoster()	refId schoolYear	XRosterType	Single Roster by refId.
xLeas/{refId}/xRosters	getXRostersByXLea()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XRosterType>	Returns Rosters associated to a specific Lea by refId.
xSchools/{refId}/xRosters	getXRostersByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XRosterType>	Returns Rosters associated to a specific School by refId.
xCourses/{refId}/xRosters	getXRostersByXCourse()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XRosterType>	Returns Rosters associated to a specific Course by refId.
xStaffs/{refId}/xRosters	getXRostersByXStaff()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XRosterType>	Returns Sections associated to a specific Staff by refId.
xStudents/{refId}/xRosters	getXRostersByXStudent()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XRosterType>	Returns Rosters associated to a specific Student by refId.

xStaffs	getXStaffs()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XStaffType>	All Staff.
xStaffs/{refId}	getXStaff()	refId schoolYear	XStaffType	Single Staff by refId.
xLeas/{refId}/xStaffs	getXStaffsByXLea()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStaffType>	Returns Staff associated to a specific Lea by refId.
xSchools/{refId}/xStaffs	getXStaffsByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStaffType>	Returns Staff associated to a specific School by refId.
xCourses/{refId}/xStaffs	getXStaffsByXCourse()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStaffType>	Returns Staff associated to a specific Course by refId.
xRosters/{refId}/xStaffs	getXStaffsByXRoster()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStaffType>	Returns Staff associated to a specific Roster by refId.

xStudents	getXStudents()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XStudentType>	All Students.
xStudents/{refId}	getXStudent()	refId schoolYear	XStudentType	Single Student by refId.
xLeas/{refId}/xStudents	getXStudentsByXLea()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStudentType>	Returns Students associated to a specific Lea by refId.
xSchools/{refId}/xStudents	getXStudentsByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStudentType>	Returns Students associated to a specific School by refId.
xRosters/{refId}/xStudents	getXStudentsByXRoster()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStudentType>	Returns Students associated to a specific Roster by refId.
xStaffs/{refId}/xStudents	getXStudentsByXStaff()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStudentType>	Returns Students associated to a specific Staff by refId.
xContacts/{refId}/xStudents	getXStudentsByXContact()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XStudentType>	Returns Students associated to a specific Contact by refId.

xContacts	getXContacts()	navigationPage navigationPageSize opaqueMarker schoolYear	List<XContactType>	All Contacts.
xContacts/{refId}	getXContact()	refId schoolYear	XContactType	Single Contact by refId.
xLeas/{refId}/xContacts	getXContactsByXLea()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XContactType>	Returns Contacts associated to a specific Lea by refId.
xSchools/{refId}/xContacts	getXContactsByXSchool()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XContactType>	Returns Contacts associated to a specific School by refId.
xStudents/{refId}/xContacts	getXContactsByXStudent()	refId navigationPage navigationPageSize opaqueMarker schoolYear	List<XContactType>	Returns Contacts associated to a specific Student by refId.

Returning Data in JSON or XML Format

As an alternative, service paths in RIC One API can be returned as a String in JSON or XML format. An overloaded method getJsonXml(), is accessible to developers. It uses enumerator values to specify the xPress data method to be called when making a request. To specify the return format, the enumerator MediaTypeEnum must be used.

* Italicized parameters are optional

Method	Parameters	Return Type	Translation

getJsonXml()	servicePath mediaType navigationPage navigationPageSize schoolYear	String	Request String response of a service path in JSON or XML format.
getJsonXml()	servicePath refId mediaType navigationPage navigationPageSize schoolYear	String	Request String response of a service path by refId in JSON or XML format.
getJsonXml()	servicePath idType id mediaType schoolYear	String	Request String response of a service path by BEDS code or Local Id in JSON or XML format.
getJsonXml()	servicePath opaqueMarker mediaType navigationPage navigationPageSize	String	Request value changes from a given point on a service path in JSON or XML format.
getJsonXml()	servicePath auppEnum mediaType navigationPage navigationPageSize	String	Request String response of a service path for AUPP in JSON or XML format.

Example Usage

getJsonXml(ServicePath.GETXLEAS, MediaTypeEnum.JSON);

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	Notes

xSchools/{refId}/xStaffs?createUsers=true	createXStaffUsers()	refId	void	Create Staff usernames and passwords for a specific School by refId.	Deprecated as of 1.8.0.
xSchools/{refId}/xStaffs?deleteUsers=true	deleteXStaffUsers()	refId	void	Delete generated Staff passwords for a specific School by refId.	Deprecated as of 1.8.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.8.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.8.0.
xSchools/{refId}/xStudents?deleteUsers=true	deleteXStudentUsers()	refId	void	Delete generated Student passwords for a specific School by refId.	Deprecated as of 1.8.0.
xSchools/{refId}/xStudents?deleteUsers=true&usernames=true	deleteXStudentUsernamesPasswords()	refId	void	Delete generated Student usernames passwords for a specific School by refId.	Deprecated as of 1.8.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 can be found under Changes Since in the API Developer’s Guide.

GetLastPage

Is an overloaded method accessible to developers. 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}

Enumerators

For more information on available enumerators and values, see the javadoc included with the library.

Enumerator	Translation
AUPPEnum	Supported AUPP requests of Create, Delete, and Get.
MediaTypeEnum	Supported return media types are JSON and XML.
ServicePath	Supported Service Paths in RIC One API.

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(ServicePath.GETXROSTERS, navigationPageSize); 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(ServicePath.GETXROSTERSBYXLEA, l.getRefId(), navigationPageSize); 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