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:

HTTP request from 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://www.itslearning.com/RestApi/PersonService.svc/Person

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:

<Person xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Address1>Edvard griegs vei 3</Address1>
<Address2/>
<Birthday>1970-01-01</Birthday>
<CellularPhone>123456</CellularPhone>
<CustomString1>StudentNo1231</CustomString1>
<CustomString1Id>StudentNumber</CustomString1Id>
<CustomString2/>
<CustomString2Id/>
<CustomString3/>
<CustomString3Id/>
<CustomString4/>
<CustomString4Id/>
<CustomString5/>
<CustomString5Id/>
<EMail>myemail@address.com</EMail>
<FirstName>Ola</FirstName>
<LastName>Nordmann</LastName>
<LastOnlineUtc>2010-10-03T20:39:48Z</LastOnlineUtc>
<PersonId>1</PersonId>
<PersonProfileId>7</PersonProfileId>
<Phone>123456</Phone>
<PostAddr>Bergen</PostAddr>
<PostalCode>5059</PostalCode>
<SyncPersonKey>123</SyncPersonKey>
<UserName>admin</UserName>
</Person>

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
(only available with OAuth session and personId must be the current user)

Returns

Array of organizations the person is member of

Response data example:

<EntityList xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CurrentPageIndex>0</CurrentPageIndex>
<EntityArray>
<Organization>
<HierarchyId>1</HierarchyId>
<LegalId>FK</LegalId>
<Title>Fylkeskommune</Title>
<Type>Site</Type>
</Organization>
<Organization>
<HierarchyId>6</HierarchyId>
<LegalId>S-B</LegalId>
<Title>School B</Title>
<Type>School</Type>
</Organization>
</EntityArray>
<PageSize>2</PageSize>
<Total>2</Total>
</EntityList>

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
(only available with OAuth session and personId must be the current user)

Returns

Array of organization roles

Response data example:

<EntityList xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CurrentPageIndex>0</CurrentPageIndex>
<EntityArray>
<OrganizationRole>
<HierarchyId>1</HierarchyId>
<Role>Teacher</Role> <!-- Enum (Administrator, Teacher, Student, Guest) -->
<HomeOrganization>True</HomeOrganization> <!-- Enum(True, False) -->
</OrganizationRole>
<OrganizationRole>
<HierarchyId>6</HierarchyId>
<Role>Teacher</Role> <!-- Enum (Administrator, Teacher, Student, Guest) -->
<HomeOrganization>True</HomeOrganization> <!-- Enum(True, False) -->
</OrganizationRole>
<OrganizationRole>
<HierarchyId>8</HierarchyId>
<Role>Guest</Role> <!-- Enum (Administrator, Teacher, Student, Guest) -->
<HomeOrganization>False</HomeOrganization> <!-- Enum(True, False) -->
</OrganizationRole>
</EntityArray>
<PageSize>3</PageSize>
<Total>3</Total>
</EntityList>

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>