LinkLocker API Documentation (Version 1)

The LinkLocker API provides a number of methods for both reading from and writing to LinkLocker accounts. Authentication is handled via an implementation of OAuth 2.

Table of Contents

Authentication

The LinkLocker API's OAuth 2 authentication mechanism allows third-party applications to access LinkLocker data on behalf of a resource owner (a LinkLocker user) without storing that resource owner's credentials locally. Developers and other consumers of the API must register their applications. Registered applications will be assigned a client ID and a client secret; these values must be kept confidential, and should be known only to your client application (note that public clients, such as serverless JavaScript applications, are prohibited by the terms within the API's Developer Agreement).

All clients must authenticate using the OAuth 2 Authorization Code grant type, using the corresponding authentication flow. Any mobile applications built using the API must handle the authorization step in the system-native browser (or in an SFSafariViewController on iOS); authorization within an embedded Web view is insecure, and is prohibited.

Auth Code Request Endpoint (GET)

https://linklocker.co/oauth/authorize

The user authorization link should be built on this endpoint, with the following URL parameters specified in a GET request:

  • client_id Required: string The client ID that you received from LinkLocker when you registered your application
  • redirect_uri Required: string Must match the callback URL that you supplied during application registration. The callback URL where users will be sent after authorization. In native applications, a URL with a custom URL scheme is best.
  • response_type Required: string Must be set to "code."
  • scope Required: string Must be set to "readwrite," which is currently the only scope allowed, and also the default in cases where it isn't specified
  • state Recommended: string This parameter can be used to pass application state back to the application after authentication; if this usage is not needed, you may supply a random string and check for it after authentication to prevent request forgery attacks.

Access Token Request Endpoint (POST)

https://linklocker.co/oauth/token

Once the user has authorized your application, the Auth Code Request will return a code parameter back to your specified redirect_uri. Use this code in a POST request sent to the /oauth/token endpoint, with the remaining parameters as follows:

  • grant_type Required: string Must be set to "authorization_code"
  • code Required: string The code you received in the response to your request in the previous step
  • client_id Required: string The client ID that you received from LinkLocker when you registered your application
  • client_secret Required: string The client secret that you received from LinkLocker when you registered your application
  • redirect_uri Required: string Must match the callback URL that you supplied during application registration.

The response to this request will contain, among other things, an access_token and a refresh_token. The former is sent in the Authorization header of all of your API requests, and expires every hour for security reasons. The refresh_token can then be used to obtain a new access_token after the previous one has expired.

To use the refresh_token to obtain a new access_token, send another POST request to the https://linklocker.co/oauth/token endpoint with the following parameters:

  • grant_type Required: string Must be set to "refresh_token"
  • refresh_token Required: string The refresh_token that was received at the time the last access_token was obtained.

The response to the refresh_token request looks the same as the response to an access_token request, and contains new access and refresh tokens.

Rate Limits

All API endpoints are rate-limited to one request per second, with bursts of 10 requests permitted. Requests which supercede the burst limit will be placed in a queue and then processed at a rate of one request per second until the queue is emptied.

Please don't overdo it. Clients which are deemed to be hammering the API excessively will be banned.

Pagination

Most of the methods which can return more than one of the user's links accept pagination parameters; pagination support (or lack thereof) is indicated in the entry for each method below.

The following pagination parameters can be provided in the URL of GET requests sent to supported endpoints:

Example URL:

https://linklocker.co/api/v1/recent-links?offset=10&limit=15

An authenticated request sent to this URL will skip over the user's ten most recent links, beginning at the 11th link. From there, it will return the next 15 most-recent links.

The responses to paginated methods, as is shown below in the examples, contain items called count and returned. count indicates the total number of links in the user's account which meet the specified criteria, independent of pagination. returned indicates the actual number of link items returned in the response.

A Note on Example Responses

In the below documentation of API methods, example responses are given in most cases. Some methods lack examples; those methods' responses are in the same format as those belonging to methods of similar types. For example, all methods which return a list of links will return the same response format.

API Methods

Update (GET)

Pagination: No

https://linklocker.co/api/v1/update

Retrieves a timestamp set at the time of the user's last interaction with his / her data. Applicable interactions include adding, editing, or deleting a link, as well as editing the state of the "starred" and "readlater" parameters.

This timestamp can be used to keep user data synchronized between the LinkLocker servers and your application; for example, you might compare it with a local timestamp to see if the data on the server has changed since your application last posted data.

Example response:

{
  "last_updated": "2017-05-30T22:26:48Z"
}

Get All (GET)

Pagination: No

https://linklocker.co/api/v1/get-all

Returns a complete list of all the user's links. Also returns a value called count, which represents the total number of links saved to the user's account.

Note that there is no pagination on this method; use it only as a brute-force means of gathering all of the customer's data. In most cases, you should use /recent-links instead.

Example response:

{
  "count": 2, 
  "links": [
        {
         "category": "uncategorized",
         "description": "Corn pone (sometimes referred to as \"Indian pone\") is a type of cornbread made from a thick, malleable cornmeal dough (which is usually egg-less and milk-less) and cooked in a specific type of iron pan over an open fire (such as a frontiersman would use), using butter, margarine, shortening, or cooking oil.", 
         "id": 1235, 
         "link": "https://en.wikipedia.org/wiki/Cornbread", 
         "readlater": false, 
         "starred": true, 
         "tags": [
           "food", 
           "corn"
         ], 
         "title": "Wikipedia: Corn Pone", 
         "ts": "2017-05-30 20:31"
        },  
        {
         "category": "favorites",
         "description": "Donec porta neque vel urna rhoncus placerat. Aenean neque nunc, bibendum quis suscipit quis, commodo in velit. Proin tempor rutrum urna eget blandit. Morbi scelerisque molestie ipsum quis sagittis. In dapibus velit ut urna tempor aliquet. Quisque eu dolor enim. Praesent vehicula arcu sit amet ipsum lobortis pretium.", 
         "id": 1234, 
         "link": "http://lorem.net", 
         "readlater": false, 
         "starred": false, 
         "title": "Lorem", 
         "ts": "2017-05-20 06:55"
        }
      ], 
  "returned": 2
}

Get Recent Links (GET)

Pagination: Yes

https://linklocker.co/api/v1/recent-links

Returns a list of the user's most recently saved links. Returns 10 links by default.

Get Link by ID (GET)

Pagination: No

https://linklocker.co/api/v1/links/id/<LINK ID>

Returns a single link with the given ID.

Example Response:

{
  "links": [
    {
     "category": "uncategorized",
     "description": "Corn pone (sometimes referred to as \"Indian pone\") is a type of cornbread made from a thick, malleable cornmeal dough (which is usually egg-less and milk-less) and cooked in a specific type of iron pan over an open fire (such as a frontiersman would use), using butter, margarine, shortening, or cooking oil.", 
     "id": 1235, 
     "link": "https://en.wikipedia.org/wiki/Cornbread", 
     "readlater": false, 
     "starred": true, 
     "tags": [
       "food", 
       "corn"
     ], 
     "title": "Wikipedia: Corn Pone", 
     "ts": "2017-05-30 20:31"
    }
  ]
}

Get Link by URL (GET)

Pagination: No

https://linklocker.co/api/v1/links/url/<URL>

Returns a single link which matches the given URL.

Get Links by Date (GET)

Pagination: Yes

https://linklocker.co/api/v1/links/date/<DATE>

Returns all links saved on the given date. Date must be formatted thusly: %Y-%m-%d (e.g. 2017-30-01).

Get Links by Tag (GET)

Pagination: Yes

https://linklocker.co/api/v1/links/tag/<TAG>

Returns links with the given tag. Don't forget that tags support spaces, which must be URL-encoded.

Get Links by Category (GET)

Pagination: Yes

https://linklocker.co/api/v1/links/category/<CATEGORY>

Returns links with the given category. Don't forget that categories support spaces, which must be URL-encoded. Uncategorized links can be retrieved with "uncategorized" as the specified category.

Get Reading List (GET)

Pagination: Yes

https://linklocker.co/api/v1/reading-list

Returns the user's Reading List (links marked to be read).

Get Starred Links (GET)

Pagination: Yes

https://linklocker.co/api/v1/starred

Returns the links the user has starred.

Get Tags (GET)

Pagination: No

https://linklocker.co/api/v1/tags

Retrives an array of all the user's tags, as well as the number of links on which each tag appears. Also returns a value called count, which represents the total number of tags in the user's account.

Each item in the array of tags, in turn, countains an individual tag, as well as instance_count (the number of links which bear the tag in question).

By default, the returned data is sorted by instance_count in descending order (meaning that the most-used tags are at the top of the list, and the least-used at the bottom). Optionally, you may supply sort-order parameters thusly:

  • https://linklocker/api/v1/tags/alphabetical
  • https://linklocker/api/v1/tags/ascending
  • https://linklocker/api/v1/tags/descending

alphabetical will return a list sorted alphabetically by the name of the tag, ascending returns a list sorted by instance_count in ascending order, etc.

Example Response:

{
  "count": 4, 
  "tags": [
    {
     "instance_count": 4, 
     "tag": "linklocker"
    }, 
    {
     "instance_count": 3, 
     "tag": "example tag"
    }, 
    {
     "instance_count": 2, 
     "tag": "another example"
    }, 
    {
     "instance_count": 1, 
     "tag": "corn"
    }
  ]
}

Get Categories (GET)

Pagination: No

https://linklocker.co/api/v1/categories

Retrives an array of all the user's categories, as well as the number of links within each category. Also returns a value called count, which represents the total number of categories in the user's account.

Each item in the array of categories, in turn, countains:

  • a list of the category's ancestors, which can be used in representing the user's categorization hierarchy within your application;
  • a category's id;
  • an instance_count, the number of links within the specified category;
  • a category's name;
  • a category's parent (also available in the ancestors list, but included separately for convenience).

Example Response:

{
  "categories": [
    {
      "ancestors": [], 
      "id": 2208, 
      "instance_count": 13, 
      "name": "example category", 
      "parent": 2205
    }, 
    {
      "ancestors": [
        2208
      ], 
      "id": 2209, 
      "instance_count": 8, 
      "name": "example subcategory", 
      "parent": 2208
    }
  ], 
  "count": 2
}

Get Category (GET)

Pagination: No

https://linklocker.co/api/v1/category/<CATEGORY>

Retrives an array of metadata pertaining to a specified category. This array contains:

  • a list of the category's ancestors, which can be used in representing the user's categorization hierarchy within your application;
  • the category's id;
  • an instance_count, the number of links within the specified category;
  • the category's name;
  • the category's parent (also available in the ancestors list, but included separately for convenience).

Example Response:

{
  "category": [
    {
      "ancestors": [], 
      "id": 2195, 
      "instance_count": 3, 
      "name": "example category", 
      "parent": null
    }
  ]
}

Search (GET)

Pagination: Yes

https://linklocker.co/api/v1/search/<QUERY>

Note: To ensure than accurate results are returned, it is highly recommended that you URL-encode all input.

Returns results for supplied search term. Note that the count value represents the total number of search results found for the search term (irrespective of the number of results returned by your pagination arguments). This feature is useful for displaying to the user things like "500 results for 'LinkLocker'..." while paginating the actual displayed results.

All of the search functionality available on the site is also available here:

  • To search for a full string, enclose the string in quotation marks
  • To search for a tag, preface the query with "tag:," e.g. tag:python
  • The "+" operator is available for AND searches; note that URL-encoded spaces must surround the "+" (e.g. search + query)
  • OR searches can be performed simply by including spaces between search terms

Add a Link (POST)

Pagination: No

https://linklocker.co/api/v1/add

Example Request Body:

title=Wikipedia%3A+Corn+Pone&link=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FCornbread%23Corn_pone&description=Corn+pone+%28sometimes+referred+to+as+%22Indian+pone%22%29+is+a+type+of+cornbread+made+from+a+thick%2C+malleable+cornmeal+dough+%28which+is+usually+egg-less+and+milk-less%29+and+cooked+in+a+specific+type+of+iron+pan+over+an+open+fire+%28such+as+a+frontiersman+would+use%29%2C+using+butter%2C+margarine%2C+shortening%2C+or+cooking+oil.&tags=food%2C+corn&starred=True&readlater=True&category=food

Adds a new link to the user's account. Data must be sent via a POST request which contains (at least some of) the following parameters in its body:

  • link required: UTF-8 string The URL. Maximum length is 512 characters.
  • title required: UTF-8 string A title for the link, with a maximum of 256 characters. Usually this is taken from the linked page's title tag.
  • description: UTF-8 string A textual description or note about the link, consisting of a maximum of 1024 characters.
  • tags: UTF-8 string Must be comma-separated, can contain spaces, lowercase will be coerced. Individual tags can be any length, but the total length of the tag string must not exceed 400 characters.
  • category: UTF-8 string Can contain spaces, lowercase will be coerced. The total length of the category string must not exceed 100 characters. Will create a new category by this name if one does not exist. If input is "none," the category's parent will be set to null, and it will thus be at the top level of the hierarchy.
  • starred: Boolean true is starred, false (default) is not starred
  • readlater: Boolean true is marked to be read later, false (default) is unmarked

Example Response:

{
  "add": "Success!"
}

Edit Link (PUT)

Pagination: No

https://linklocker.co/api/v1/edit

Edits an existing link given that link's (required) ID via a PUT request, with any and/or all of the following parameters given in the request body:

  • id required: Integer The link's ID.
  • edit_link: UTF-8 string The URL. Maximum length is 512 characters.
  • edit_title: UTF-8 string A title for the link, with a maximum of 140 characters. Usually this is taken from the linked page's title tag.
  • edit_description: UTF-8 string A textual description or note about the link, consisting of a maximum of 1024 characters.
  • edit_tags: UTF-8 string Must be comma-separated, can contain spaces, lowercase will be coerced. Individual tags can be any length, bu the total length of the tag string must not exceed 400 characters.
  • edit_category: UTF-8 string Can contain spaces, lowercase will be coerced. The total length of the category string must not exceed 100 characters. Will create a new category by this name if one does not exist. If input is "uncategorized," the link will be marked as such. Integer input will be coerced to a string.
  • edit_starred: Boolean true is starred, false (default) is not starred.
  • edit_readlater: Boolean true is marked to be read later, false (default) is unmarked.

Example Response:

{
  "edit": "Success!"
}

Delete Link (DELETE)

Pagination: No

https://linklocker.co/api/v1/delete/<LINK ID>

Deletes the link with the given ID.

Example Response:

{
  "delete_link_1234": "Deleted!"
}

Create Category (POST)

Pagination: No

https://linklocker.co/api/v1/create-category

Example Request Body:

category=example&parent=none

Adds a new category to the user's account and returns the new category's ID. Data must be sent via a POST request which contains the following parameters in its body.

  • category required: UTF-8 string The category's name. Maximum length is 100 characters.
  • parent UTF-8 string Optionally, you can specify the new category's parent (the new category will be nested within the parent, becoming its subcategory). If the specified value is "none," the category's parent will be set to null, and it will thus be at the top level of the hierarchy.

Example Response:

{
  "id": "2219"
}

Edit Category (PUT)

Pagination: No

https://linklocker.co/api/v1/category/edit

Example Request Body:

id=2219&name=example&parent=favorites

Edits an existing category given that category's (required) ID via a PUT request.

  • id required: Integer The category's ID.
  • name: UTF-8 string The category's name. Maximum length is 100 characters. If none is specified, no change will be made.
  • parent UTF-8 string OR Integer Specify a new parent for the category if desired. You may specify either the name of an existing parent category or the parent's id value. If no value is specified, no change will be made. If the specified value is "none," the category's parent will be set to null, and it will thus be at the top level of the hierarchy.

Example Response:

{
  "id": 2219, 
  "name": "example", 
  "parent": 1596
}

Delete Category (DELETE)

Pagination: No

https://linklocker.co/api/v1/category/delete/<CATEGORY NAME>

Deletes the category named in the URL. All links with this category will be changed to "UNCATEGORIZED." Any child categories will be adopted by the deleted category's parent, if any. Don't forget that categories support spaces, which must be URL-encoded.

Example Response:

{
  "delete_category_example": "Deleted!"
}