RIC One API Java Client Library
Returning Data in JSON or XML Format
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 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. |
|
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 schoolYear |
List<XLeaType> |
All Leas. |
xLeas |
getXLeas() |
opaqueMarker navigationPage navigationPageSize |
List<XLeaType> |
All Leas from a certain point in time. |
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 schoolYear |
List<XLeaType> |
Returns Leas associated to a specific School 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> |
All Schools. |
xSchools |
getXSchools() |
opaqueMarker navigationPage navigationPageSize |
List<XSchoolType> |
All School value changes from a given point. |
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 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> |
All Calendars. |
xCalendars |
getXCalendars() |
opaqueMarker navigationPage navigationPageSize |
List<XCalendarType> |
All Calendar value changes from a given point. |
xCalendars/{refId} |
getXCalendar() |
refId schoolYear |
XCalendarType |
Single Calendar by refId. |
xLeas/{refId}/xCalendars |
getXCalendarssByXLea() |
refId navigationPage navigationPageSize schoolYear |
List<XCalendarType> |
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> |
All Courses. |
xCourses |
getXCourses() |
opaqueMarker navigationPage navigationPageSize |
List<XCourseType> |
All Course value changes from a given point. |
xCourses/{refId} |
getXCourse() |
refId schoolYear |
XCourseType |
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> |
Courses associated to a specific School by refId. |
xRosters/{refId}/xCourses |
getXCoursesByXRoster() |
refId navigationPage navigationPageSize schoolYear |
List<XCourseType> |
Courses associated to a specific Roster by refId. |
xRosters |
getXRosters() |
navigationPage navigationPageSize schoolYear |
List<XRosterType> |
All Rosters. |
xRosters |
getXRosters() |
opaqueMarker navigationPage navigationPageSize |
List<XRosterType> |
All Roster value changes from a given point. |
xRosters/{refId} |
getXRoster() |
refId schoolYear |
XRosterType |
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> |
All Staff. |
xStaffs |
getXStaffs() |
opaqueMarker navigationPage navigationPageSize |
List<XStaffType> |
All Staff value changes from a given point. |
xStaffs/{refId} |
getXStaff() |
refId schoolYear |
XStaffType |
Single Staff by refId. |
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 |
getXStudents() |
navigationPage navigationPageSize schoolYear |
List<XStudentType> |
All Students. |
xStudents |
getXStudents() |
opaqueMarker navigationPage navigationPageSize |
List<XStudentType> |
All Student value changes from a given point. |
xStudents/{refId} |
getXStudent() |
refId schoolYear |
XStudentType |
Single Student by refId. |
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> |
All Contacts. |
xContacts |
getXContacts() |
opaqueMarker navigationPage navigationPageSize |
List<XContactType> |
All Contact value changes from a given point. |
xContacts/{refId} |
getXContact() |
refId schoolYear |
XContactType |
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 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 |
xSchools/{refId}/xStaffs?createUsers=true |
createXStaffUsers() |
refId |
void |
Create Staff usernames and passwords for a specific School by refId. |
xSchools/{refId}/xStaffs?deleteUsers=true |
deleteXStaffUsers() |
refId |
void |
Delete generated Staff passwords for a specific School by refId. |
xSchools/{refId}/xStaffs?deleteUsers=true&usernames=true |
deleteXStaffUsernamesPasswords() |
refId |
void |
Delete generated Staff usernames and 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 |
void |
Create Student usernames and passwords for a specific School by refId. |
xSchools/{refId}/xStudents?deleteUsers=true |
deleteXStudentUsers() |
refId |
void |
Delete generated Student passwords for a specific School by refId. |
xSchools/{refId}/xStudents?deleteUsers=true&usernames=true |
deleteXStudentUsernamesPasswords() |
refId |
void |
Delete generated Student usernames 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() |
getXCoursess() |
getXRosters() |
getXStaffs() |
getXStudents() |
getXContacts() |
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"; |
Retrieve Endpoints
All Endpoints
for(Endpoint e : 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.getHref()); |
Retrieve a Single Object
Return a single xLea
XPress xPress = new XPress(e.getHref()); |
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; |
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; |
Example
import riconeapi.models.authentication.Endpoint; |
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