Lingk REST APIs
Using the Lingk REST APIs
Table of Contents
Getting Started
With Lingk's data integration platform, you can centralize data, integration and documentation. Each Account has a dedicated API endpoint and credentials.
Authentication
HMAC signatures
HMAC Signing is an access token method that adds another level of security by forcing the requesting client to also send along a signature that identifies the request temporarily to ensure that the request is from the requesting user, using a secret key that is never broadcast over the wire.
The HTTP Signatures standard provides a standardized way of signing HTTP requests. Lingk supports the HTTP Signatures standard using SHA-1 encrypted HMACs. Signatures expire 10 seconds after creation.
An HMAC signature is essentially some additional data sent along with a request to identify the end-user using a hashed value. In our case, we encode the 'date' header, HTTP method, and endpoint of a request, the algorithm would look like:
urlEncode(base64Encode(SHA1("date:Mon, 02 Jan 2006 15:04:05 MST\n(request-target): GET /v1/ps/@self/contacts”, secret_key))
The full request header for an HMAC request uses the standard Authorization header, and uses set, stripped comma-delimited fields to identify the user, from the draft proposal:
Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1",headers="date (request-target)",signature="urlEncode(base64Encode(SHA1("date: Mon, 02 Jan 2006 15:04:05 MST\n(request-target): GET /v1/ps/@self/contacts”, secret_key))"
The date format for an encoded string is:
Mon, 02 Jan 2006 15:04:05 MST
This data format is the standard for most browsers, but it worth noting that if the above format is not how the date HTTP header is encoded the request will fail.
A curl example of a valid request:
For implementations in various languages, go to Code Samples.
API Context
The context of an API request for Lingk.
Attributes
Name
Type
Description
Example
self
string
Reference to authentication context.
"@self"
tenantKey
string
Unique key for the tenant. See the Developer Console for your key.
"centralu"
appKey
string
Unique key for the application. See the Developer Console for your key.
"studentsystem"
API Errors
When an exception occurs, an HTTP code will be returned and a JSON response. In the JSON response, will be an error code.
HTTP Code
Error Code
Description
409
102
Validation: Conflict
409
103
Validation: Conflict
412
104
Validation: Precondition failed. Often related to using an invalid External ID.
400
105
Validation: Precondition failed. Often related to using an invalid Tenant or App in Data Consumer URIs.
500
106
System: Internal Error
401
107
Validation: Inaccessible resource. You may not have access to this resource.
422
Validation: Unprocessable entity. Check your JSON format.
Paging
Lingk APIs return data in pages. Each page is by default sorted by lastModifiedDate.
Name
Type
Description
Example
limit
string
Number of records returned per GET request. Defaults to 25.
25
offset
string
Page of data to return. Defaults to 1.
2
Use Cases
Returning data for the second page
Returning more than 25 records per page
Returning data for another page with a defined limit
Filtering
Lingk APIs allow filtering by string or data values. Lingk supports advanced filtering scenarios through the filter parameters. Common supported scenarios are:
Selecting sections for a given calendar session
Selecting updated section information
By String Value
Lingk supports filtering by string values. The filter query string parameter supports the following string operations.
Name
Type
Description
Example
eq
string
Equals
"&filter=calendarSessionExternalId eq winter2015"
By Date Value
Lingk supports filtering by RFC3339 formatted date values. The filter query string parameter supports the following date operation.
Name
Type
Description
Example
lt
date
Less Than
"&filter=lastModifedDate lt 2015-01-02T15:04:05-07:00"
lte
date
Less Than or Equal
"&filter=lastModifedDate lte 2015-01-02T15:04:05-07:00"
gt
date
Greater Than
"&filter=lastModifedDate gt 2015-01-02T15:04:05-07:00"
gte
date
Greater Than or Equal
"&filter=lastModifedDate gte 2015-01-02T15:04:05-07:00"
Compound Filters
Multiple filters can be used in a single request. Each filter is added as a separate filter query string parameter.
&filter=lastModifedDate gt 2015-01-02T15:04:05-07:00&filter=courseNumber eq 101_avc
Retrieves all Courses modified since 2015-01-02 that have a Course Number equalling "101_avc"
Last updated