# Lingk REST APIs

## Using the Lingk REST APIs

### Table of Contents

* [Getting Started](/lingk-apis.md#start)
* [Authentication](/lingk-apis.md#authentication)
  * [API Context](/lingk-apis.md#context) 
* [Paging](/lingk-apis.md#paging)         
* [Filtering](/lingk-apis.md#filtering)  
  * [By String Values](/lingk-apis.md#string)  
  * [By Date Values](/lingk-apis.md#date)  
  * [Compound Filters](/lingk-apis.md#compound)     
* [API Errors](/lingk-apis.md#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"


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.lingk.io/lingk-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.