Authenticating API requests
At LinkedIn, we value the integrity and security of our members' data above all else. In order for your applications to access LinkedIn member data and/or act on their behalf, they must be authenticated. LinkedIn relies on the industry standard OAuth 2.0 protocol for granting access, due to its simplicity and ease of implementation.
Please read our Authenticating with OAuth 2.0 guide for a detailed walk-through of how to get your application authenticated and successfully interacting with LinkedIn's REST APIs.
Additionally, there are several 3rd party libraries available in the open source community that abstract the OAuth 2.0 authentication process for you in every major programming language.
Requesting data from the APIs
Unless otherwise specified, all of LinkedIn's APIs will return the information that you request in the XML data format.
If it is more convienent for your application to work with data in JSON format, you can request that APIs return you JSON data using one of the following methods:
- Add a format=json URL argument to the end of your API call.
- Add this HTTP header to your API call: x-li-format: json
Due to the unique natures of these two data formats, there are some subtle differences in the field identifiers you will encounter in the output. Make a sample API call using the format you intend your application to work with to ensure that you know exactly how to reference the information you are seeking within the response.
Sending data to the APIs
Certain API calls (e.g. Share with LinkedIn) require you to send data in a particular format as part of the API call. By default, all API calls expect input in XML format, however if it is more convenient for your application to submit data in JSON format, you can inform the APIs that they will be receiving a JSON-formatted payload by including the following two HTTP header values in the call:
- Content-Type: application/json
- x-li-format: json
Every API call that requires data to sent by POST or PUT has a different data structure that it expects in the payload. Refer to the sample documentation for the specific call you are making to see the exact XML and JSON payload formats to complete your request.
Understanding request throttling
All REST API requests are throttled to prevent abuse and ensure stability. The exact number of calls that your application can make per day varies based on the type of request you are making. You will find this information along side the documentation for each specific API call.
There are three different kinds of throttles in place:
- Application Throttle — The total number of calls that your application can make in a day.
- User Throttle — The total number of calls that any unique individual member using your application can make in a day.
- Developer Throttle — The total number of calls that any user that is identified as a "developer" in the Application's settings can make in a day.
Please note that for the purposes of request throttling, the API server's "day" is defined as the 24 hour period beginning at midnight UTC and ending at midnight on the following day.
Handling Paged Responses
When making calls that return a large number of results as a list, it will often be of benefit to page the result set. By requesting smaller subsets of data, you will get a response much faster than when requesting the entire, potentially large, data set.
On calls that support result set paging, pass in the following parameters to control size and start point of the page:
|start||The index of the first item you want results for.|
|count||The maximum number of items you want included in the result set. Note that there may be less remaining items than the value you specify here.|
To page through the results, begin with a start value of 0 and a count value of N. To get the next page, set start value to N, while the count value stays the same. Subsequent pages will start at 2N, 3N, 4N...
You will have paged through all the results once your start value + count value >= the value of "_total" in the result set.