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:

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

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.

Paging

Lingk APIs return data in pages. Each page is by default sorted by lastModifiedDate.

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.

By Date Value

Lingk supports filtering by RFC3339 formatted date values. The filter query string parameter supports the following date operation.

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