This article applies to connections using OAuth 1.0, which is no longer supported by 1EdTech. Connections using OAuth 1.0 cannot be enabled.
The REST Doc Client provides consumers of the API the means of discovering available resources and implement methods. The client allows users to verify and test endpoints exposed through the API.
The Campus OneRoster API allows districts to integrate 3rd party applications with Campus by retrieving information from Campus such as roster, student, and teacher data. OneRoster is a set of specifications established by the IMS Global Learning Consortium. The REST Documentation Client allows users to test and validate this API by issuing HTTP requests and reviewing the responses.
The Rest Documentation Client can be used to modify data through PUT and DELETE methods. Campus recommends testing OneRoster API calls using those methods via a district's sandbox environment and not in production.
Key Concepts
- Resources are objects with associated data and a set of methods to operate on it.
- Endpoints are unique URLs that represents an object or collection of objects. The endpoint is used by the HTTP client to interact with data resources.
- Models represent data objects. Aside from the model name, the model contains a description, along with properties that define the contained elements and data types.
- Path includes the URL for accessing the resource endpoints.
- Method is an operation or action that can be performed on a resource.
The REST Doc Client handles URL encoding by replacing unsafe ASCII characters with a "%" followed by two hexadecimal digits. For more information on URL encoding visit http://www.w3schools.com/tags/ref_urlencode.asp
OneRoster Walkthrough
- Log Into the REST Doc Client
- The REST Doc client exposes sensitive SIS data and therefore requires authentication.
- The user is granted full access to all resources based on the available actions.
- Granular calendar or tool rights are not supported.
- This account is not linked with any Campus SIS accounts.
- The credentials are based on the Consumer Key and Secret configured on that specific district edition.
- Browse or Search for Resources
- Before any requests can be submitted, the user must first identity what resource they would like to access.
- The resources are based on OneRoster object naming conventions
- Review the associated model
- Access the resource models to familiarize yourself with the mapped data
- Close the model when you are done reviewing it.
- Select a request method (action)
- Determine which method you would like to perform on the resource based on the provided description
- Some paths require additional parameters be provided in order to issue a request. (In the example below I would need to enter a Section.sectionID)
PUT Methods require input content. (In the example below I am posting a Result (GradingScore record) with the required date, score (percent) and custom letter grade (score) fields:
- The REST Doc client supports pagination
- Set the following values to override the defaults: Limit = Number of Records per Page, Offset = Starting Record
- Set the following values to override the defaults: Limit = Number of Records per Page, Offset = Starting Record
Additional custom filters can be added for GET Methods
The filter needs to be added to the request, otherwise the value will be ignored.
- The filter syntax always starts with the string prefix of "filter="+fieldName+filterType+"'"+value+"'"
- Values are enclosed in single quotes, regardless of dataType (i.e. not just for text but for IDs and Booleans too)
- Note: Field names are case sensitive
Below is an example of the syntax for filtering based off a single field value.
Here is an example of a contains filter:
filter=usernamecontains'Bob.Marley'- Once added the filters will appear above, and can be edited or removed before submitting the request.
- The filter syntax always starts with the string prefix of "filter="+fieldName+filterType+"'"+value+"'"
- Determine which method you would like to perform on the resource based on the provided description
- Submit the request in order to retrieve a response
- Review the response
- The response is formatted as JSON, which is similar to XML.
- It displays data organized by a hierarchy of tags; starting with the object, embedded elements and values, and followed by any linked objects and their values.
- The status code reveals whether or not the request was successfully satisfied.
- The response is formatted as JSON, which is similar to XML.
