REST API 入门

领英所有数字集成程序的基础

REST API 是领英所有程序集成的核心。所有其他互动方法 (如 JavaScript 和 Mobile SDK) 仅是围绕 REST API 的包装器,旨在为开发人员打造更便捷的体验。因此,即使您是在进行移动端或 JavaScript 开发,仍值得花点时间熟悉 REST API 的运作方式以及其功能。

验证 API 请求

在领英,我们重视会员数据的完整性和安全性胜于一切。如果您的应用想要访问领英会员的数据并/或代表他们采取行动,则必须获得验证。领英根据行业标准 OAuth 2.0 协议授予访问权限,而此协议实施起来十分简单、轻松。

请阅读使用 OAuth 2.0 验证指南,详细了解如何使应用获得验证并与领英 REST API 成功互动。

此外,开源社区中提供数个第三方库,它们以各种主要编程语言为您提炼 OAuth 2.0 验证流程的内容。

数据格式

向 API 请求数据

除非另有规定,否则领英所有 API 将以 XML 数据格式返回您请求的信息。

GET
https://api.linkedin.com/v1/people/~
响应示例
<?xml version="1.0" encoding="UTF-8"?>
<person>
  <id>1R2RtA</id>
  <first-name>Frodo</first-name>
  <last-name>Baggins</last-name>
  <headline>Jewelery Repossession in Middle Earth</headline>
  <site-standard-profile-request>
    <url>https://www.linkedin.com/profile/view?id=…</url>
  </site-standard-profile-request>
</person>

如果您的应用更擅长处理 JSON 格式的数据,您可按照以下任一种方法请求 API 返回 JSON 数据:

  1. 在 API 调用结尾处添加一个 format=json 网址参数。
  2. 在 API 调用中添加此 HTTP 标头: x-li-format: json

例如:

GET
https://api.linkedin.com/v1/people/~?format=json
响应示例
{
  "firstName": "Frodo",
  "headline": "Jewelery Repossession in Middle Earth",
  "id": "1R2RtA",
  "lastName": "Baggins",
  "siteStandardProfileRequest": {
    "url": "https://www.linkedin.com/profile/view?id=…"
  }
}

由于这两种数据格式各有其独特之处,因此您在输出时可能会遇到字段标识存在细微差别的情况。请在请求示例 API 调用时说明您希望应用处理的格式,确保您充分了解如何参考在此响应中寻求的信息。


向 API 发送数据

某些 API 调用 (例如与领英分享) 要求您在 API 调用期间以特定格式发送数据。默认情况下,所有 API 调用需采用 XML 格式输入。但是如果应用提交 JSON 格式的数据更为方便,则您可在调用请求中添加以下两个 HTTP 标头值,以此告知 API 它们将收到 JSON 格式的净负荷:

  1. Content-Type: application/json
  2. x-li-format: json

请求通过 POSTPUT 发送数据的每个 API 调用,其数据结构与净负荷所要求的结构不同。请参照与您特定调用相关的示例文档,了解完成请求所需的确切 XML 和 JSON 净负荷格式。

了解请求限制

为避免滥用和确保稳定性,所有 REST API 请求均会受到限制。根据发起请求的类型,应用每天可调用的确切次数会有所不同。您可在每个特定 API 调用文档旁找到此信息。

目前采取三种不同的限制方式:

  • 应用限制 - 应用每天可调用的总次数。
  • 用户限制 - 单个个体成员每天可使用应用调用的总次数。
  • 开发人员限制 - 在应用设置中被确定为“开发人员”的用户每天可调用的总次数。
鉴于请求限制的目的,API 服务器的“天”是指为始于 UTC (协调世界时) 午夜时分、止于第二天午夜时分的 24 小时周期。

处理分页响应

如果预计调用将以列表形式返回大量结果,我们建议对结果集进行分页排序。 与请求可能较大的、完整数据集的响应速度相比,请求较小数据子集的速度会更快。

对于支持结果集分页排序功能的调用请求,请发送以下参数,以控制页面的尺寸和起始点:

分页参数

名称
说明
start 您想要获得结果的第一个项目的索引。
count 您想在结果集中包含的最大项目数。请注意,剩余的项目数可能小于您在此处指定的值。

如要翻页浏览结果,请将起始值设为 0,将计数值设为 N。如要获取下一页,请将起始值设为 N,计数值保持不变。 后续页将以 2N、3N、4N……开头

如果结果集中的起始值 + 计数值 >= “_合计”值,您将分页浏览所有结果。

例如:

GET
https://api.linkedin.com/v1/companies/1337/updates?start=20&count=10&format=json
响应示例
{
  "_count": 10,
  "_start": 20,
  "_total": 613,
  "values":  [
      …
  ]
}