# Lingk REST APIs

## Using the Lingk REST APIs

### Table of Contents

* [Getting Started](#start)
* [Authentication](#authentication)
  * [API Context](#context) 
* [Paging](#paging)         
* [Filtering](#filtering)  
  * [By String Values](#string)  
  * [By Date Values](#date)  
  * [Compound Filters](#compound)     
* [API Errors](#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](https://tools.ietf.org/html/draft-cavage-http-signatures-05) 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](https://developers.lingk.io/code_samples.html).

### 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"