Lingk REST APIs

Using the Lingk REST APIs

Table of Contents

• Getting Started

• Authentication

  • API Context

• Paging

• Filtering

  • By String Values

  • By Date Values

  • Compound Filters

• API Errors

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:

curl -n 
-H 'Date: Wed, 25 May 2016 16:06:06 GMT' 
-H 'Authorization: Signature keyId="[yourkey]",algorithm="hmac-sha1",headers="date (request-target)",signature="a4JGzTlsExiTXVCvtZjIGjf6m50%3D"'
 https://www.lingkapis.com/v1/@self/ps/calendarsessions

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

  ?offset=2

• Returning more than 25 records per page

  ?limit=100

• Returning data for another page with a defined limit

  ?offset=2&limit=100

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

  &filter=calendarSessionExternalId eq winter2015

• Selecting updated section information

  &filter=lastModifiedDate gte 2015-01-02T15:04:05-07:00

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"