Edvard griegs vei 3 1970-01-01 123456 StudentNo1231 StudentNumber [email protected] Ola Nordmann 2010-10-03T20:39:48Z 1 7 123456 Bergen 5059 123 admin
REST API reference
Authorization:
To call the REST API we need to identify the services to use, and the build a request secured by OAuth 1.0.
Below, we describe how the data supplied by itslearning when the plugin is called corresponds to OAuth terminology and how to use them as an input to the OAuth-specified algorithm when constructing the request for the REST API:
The details and processes related to OAuth protocol are beyond the scope of this document, but the protocol is well documented and has many implementations in popular programming languages.
Here's a sample OAuth-secured call from a plugin to itslearning:
GET https://www.itslearning.com/RestApi/PersonService.svc/Person?oauth_token=30093542-3827-4b61-b49a-f4914ffa8649
&oauth_nonce=749ed646-ed13-4581-b22f-43e2e73864ba&oauth_consumer_key=aaeddd9d-6e2d-43ec-8e7c-18cd6584bc8c
&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1388856307&oauth_version=1.0&oauth_signature=Qgz8vVC%2B6%2FooIIULE7AqY%2FDZFi8%3D HTTP/1.1
Host: www.itslearning.com
Broken down into parameter-value pairs, the query string would look like this:
Parameter |
Value |
Description |
oauth_token |
30093542 - 3827 -4b61-b49a-f4914ffa8649 |
The oauth token identifier taken from the OAuthToken parameter found in incoming request. |
oauth_nonce |
749ed646-ed13- 4581 -b22f-43e2e73864ba |
A one-time code that together with timestamp protects against reply attacks. Please refer to OAuth specification for details. |
oauth_consumer_key |
aaeddd9d-6e2d-43ec-8e7c-18cd6584bc8c |
The application key / shared secret generated while registering the extension. Can be found in Developer Portal. |
oauth_signature_method |
HMAC-SHA1 |
The cryptographic algorithm used to create the signature. itslearning supports HMAC-SHA1 and this value should be the same for every request. |
oauth_timestamp |
1388856307 |
The timestamp used together with nonce to protect against reply attacks. Please refer to OAuth specification for details. |
oauth_version |
1.0 |
Version of the OAuth protocol. itslearning supports version 1.0 and this value should be the same for every request. |
oauth_signature |
Qgz8vVC%2B6%2FooIIULE7AqY%2FDZFi8%3D |
The request signature to ensure that the request has not been tampered with. One of the components used to create the signature (access token secret in OAuth terminology) is provided in incoming request as OAuthTokenSecret parameter. The other - OAuth consumer key is equal to the extension's shared secret, that can be found in Developer Portal. The detailed process of calculating the signature is described in the protocol specification. |
Combining the described values and signing them properly as OAuth specifies should provide a valid request to itslearning's REST API.
REST API base URLs
Base URL for production: https://www.itslearning.com/restapi
Services
Person
URL |
[start]/PersonService.svc/Person |
Example URL |
|
HTTP method |
GET |
Description |
Get person (current user) |
Returns |
Returns the current user |
Additional information |
To be able to call this method, your plugin must be approved for retrieving extended data for a sites users |
Response data example:
Some notes about customfields and other unintuitive data
Field |
Comments |
PersonProfileId |
Users in itslearning have profiles that govern their access to site features. This ID is mainly used by itslearning internally, but some 3rd parties find it useful for tight integrations. |
Synckey |
If used, the synckey refers to a unique value identifiying the users across multiple systems, e.g. an MIS or Active Directory. |
CustomField1 (if in use*) |
custom1id (the name for custom field 1 - trunked at 20 chars) custom1 (the value of custom field 1) The customfields can be used to populate the user objects with additional data at the customers' discretion. |
CustomField2 (if in use*) |
custom2id (the name for custom field 2 - trunked at 20 chars) custom2 (the value of custom field 2) |
CustomField3 (if in use*) |
custom3id (the name for custom field 3 - trunked at 20 chars) custom3 (the value of custom field 3) |
CustomField4 (if in use*) |
custom4id (the name for custom field 4 - trunked at 20 chars) custom4 (the value of custom field 4) |
CustomField5 (if in use*) |
custom5id (the name for custom field 5 - trunked at 20 chars) custom5 (the value of custom field 5) |
*Only transfer custom fields if name for the custom field is defined and it has a value
Organizations
URL |
[start]/PersonService.svc/Person/{PersonId}/Organizations |
Example URL |
http://www.itslearning.com/RestApi/PersonService.svc/Person/1/Organizations |
HTTP method |
GET |
Parameters |
PersonId - the personId of the person |
Description |
Gets the organizations that a person is member of |
Returns |
Array of organizations the person is member of |
Response data example:
0 1 FK Fylkeskommune Site 6 S-B School B School 2 2
Organization roles
URL |
[start]/PersonService.svc/Person/{PersonId}/OrganizationRoles |
Example URL |
http://www.itslearning.com/RestApi/PersonService.svc/Person/1/OrganizationRoles |
HTTP method |
GET |
Parameters |
PersonId - the personId of the person |
Description |
Gets the organization roles for the person |
Returns |
Array of organization roles |
Response data example:
0 1 Teacher True 6 Teacher True 8 Guest False 3 3
App licenses
URL |
[start]/AppService.svc/AppLicensesForUser |
Example URL |
http://www.itslearning.com/RestApi/AppService.svc/AppLicensesForUser |
Http methods |
GET |
Description |
Gets the licenses that current user has for the current plugin |
Returns |
Array of AppLicenses |
Response data example:
<
EntityList
xmlns:i
=
"http://www.w3.org/2001/XMLSchema-instance"
>
<
CurrentPageIndex
>0</
CurrentPageIndex
>
<
EntityArray
>
<
AppLicense
>
<
ExternalLicenseId
>S-A-2011</
ExternalLicenseId
>
<
LicenseId
>1</
LicenseId
>
</
AppLicense
>
</
EntityArray
>
<
PageSize
>1</
PageSize
>
<
Total
>1</
Total
>
</
EntityList
>