如何设计RESTful API?

1. 术语

1. 资源（Resource） 是某个东西的对象或表示，它具有一些相关的数据，并且可以有一组方法来对其进行操作。例如，动物、学校和员工是资源，删除、添加、更新是对这些资源执行的操作。
2. 集合（Collections） 是一组资源。
3. 统一资源定位符（URL） 是资源可以被定位的路径，并且可以对其执行一些操作。

2. API 端点

写一些简单的例子，假设有一些公司（Compaines），每个公司有一些员工（Employees）。

• /addNewEmployee
• /updateEmployee
• /deleteEmployee
• /deleteAllEmployees
• /promoteEmployee
• /promoteAllEmployees

不同的操作有不同个的API，其中还包含许多重复的操作。大量的API将很难维护。

2.1. 哪里错了？

URL中应该只包含资源（Resource）的名词，不应该包含操作的名词。/addNewEmployee这个URL中包含操作addNew和资源Employee。

2.2. 正确的URL

使用method GET 的URL/employee是一个好的例子。

2.3. 复数

URL中的资源名总是为复数

• method GET path /companies 获取公司列表
• method GET path /companies/34 获取34号公司的详细数据
• method DELETE path /companies/34 删除34号公司

2.4. 资源嵌套

当一些资源包含另一些资源的情况下，例如一些公司包含一些员工。

• GET /companies/3/employees 获取3号公司的所有员工列表
• GET /companies/3/employees/45 获取3号公司45号员工的数据
• DELETE /companies/3/employees/45 删除3号公司45号员工
• POST /companies 创建一个新的公司，并返回新公司的数据

3. HTTP methods

HTTP协议已经定义了几组方法，这些方法指示了要在资源上执行的操作的类型。

1. GET方法从资源请求数据，不应产生任何副作用。
2. POST方法请求服务器在数据库中创建资源。
3. PUT方法请求服务器更新资源或创建资源（如果资源不存在）。
4. DELETE方法请求将资源或其实例从数据库中删除。

3.1. 重复提交

POST、PUT操作防止重复提交需要，有两类方式

1. 幂等
2. 验证码

4. 状态码 Status codes

当客户端通过API向服务器发出请求时，客户端应该知道请求是否失败、通过或请求是否错误。 HTTP状态码是标准化代码，在各种情况下有各种解释。服务器应始终返回正确的状态码。 以下是HTTP代码的重要分类：

4.1. 成功类别 2xx

1. 200 Ok表示GET，PUT或POST成功的标准HTTP响应。
2. 201 Created 表示新的实例已经创建。例如，使用POST方法创建新实例应始终返回201状态码。
3. 204 No Content表示请求已成功处理，但没有返回任何内容。DELETE可以是一个很好的例子。DELETE /companies/43/employees/2将删除员工2,不需要API的响应主体中的任何数据，因为我们明确要求系统删除。如果有任何错误，例如数据库中不存在员工2，则响应代码将不是2xx成功类别，而是4xx客户端错误类别。

4.2. 重定向类别 3xx

1. 302 Found重定向状态响应代码指示所请求的资源已被临时移动到Location标头给定的URL。浏览器重定向到这个页面，但是搜索引擎不更新他们到资源的链接（在'SEO-speak'中，据说'link-juice'没有被发送到新的URL）。
2. 304 Not Modified表示客户端的缓存中已有响应。因此不需要再次传输相同的数据。

4.3. 错误类别 4xx

1. 400 Bad Request表明客户端的请求未被处理，因为服务器无法理解客户端要求的内容。
2. 401 Unauthorized表示客户端不允许访问资源，并且应该使用所需的凭证重新请求。
3. 403 Forbidden表示请求有效并且客户端已通过身份验证，但客户端因任何原因不允许访问该页面或资源。例如，有时授权客户端不允许访问服务器上的目录。
4. 404 Not Found表示请求的资源现在不可用。
5. 410 Gone表示请求的资源不再可用，并且已被有意移动。

4.4. 服务器错误类别 5xx

1. 500 Internal Server Error表示请求有效，但服务器完全混乱，服务器被要求提供一些意外情况。
2. 503 Service Unavailable表示服务器已关闭或无法接收和处理请求。大多数情况下，如果服务器正在进行维护。

5. 搜索、排序、过滤和分页

所有这些操作都只是对一个数据集的查询。将不会有新的API来处理这些操作。我们需要使用GET方法API附加查询参数。

• Sorting如果客户想要获得排序的公司列表，则GET /companies接口应接受查询中的多个排序参数。例如GET /companies?sort=rank_asc将按升序对公司排序。
• Filtering为了过滤数据集，我们可以通过查询参数传递各种选项。例如GET /companies?category=banking&location=india将公司列表按公司类别为银行业务和公司位于印度进行过滤。
• Searching在公司列表中搜索公司名称时，接口应该是GET /companies?search=Digital Mckinsey
• Pagination当数据集太大时，我们会将数据集分成更小的块，这有助于提高性能并更容易处理响应。例如GET /companies?page=23表示着获得第23页上的公司列表。

如果在GET方法中添加许多查询参数会导致URI过长，则服务器可能会响应414 URI过长的HTTP状态，在这些情况下，也可以在POST方法的请求主体中传递参数。

6. 版本

当你的API被全世界所使用时，通过一些重大改变来升级API也会导致使用你的API打破现有的产品或服务。
http://api.yourservice.com/v1/companies/34/employees是一个很好的例子，它具有路径中API的版本号。如果有重大更新，我们可以将这组新的API命名为v2或v1.x.x

目录

1. 术语

2. API 端点

2.1. 哪里错了？

2.2. 正确的URL

2.3. 复数

2.4. 资源嵌套

3. HTTP methods

3.1. 重复提交

4. 状态码 Status codes

4.1. 成功类别 2xx

4.2. 重定向类别 3xx

4.3. 错误类别 4xx

4.4. 服务器错误类别 5xx

5. 搜索、排序、过滤和分页

6. 版本

---