RESTful 架构-API设计

简介

REST(表述性状态转移，Representational State Transfer)是一种架构风格，它定义了创建可扩展web服务的最佳实践，这个过程会充分发挥HTTP协议的功能

特点

• 客户端-服务器端：UI是与数据存储分离的
• 无状态：每个请求会包含服务器所需的足够信息，无需维护状态就能操作
• 可缓存：服务器的响应中包含了足够的信息，客户端能够对数据存储做出合理的决策
• 统一接口：URL会标识唯一识别资源，能够通过超链接发现api
• 分层：API的每个资源都提供了更合理的细节

Richardson的成熟度模型

Leonard Richardson 定义了著名的4个等级，从0级到3级，它们描述了Web API的“RESTful程度”。每个等级都需要开展额外的工作，并在API方面进行投入，但是这也会带来额外的收益。原文地址

第0级-HTTP

第0级非常容易实现，只需要让资源能够在网络上通过HTTP协议获得即可（JSON，XML等）

第1级-资源

资源是模型中某个元素的唯一标识符，借助HTTP，资源会与一个URL进行关联。
如：/users 获得所有的用户列表
/users/12/ 获得特定用户信息

第2级-HTTP动作

这个级别是使用HTTP动作来识别资源可能的行为。

• GET(select)：读取资源
• PUT(update)：更新资源
• POST(create)：新建资源
• DELETE(delete)：删除资源
  如：
POST /users HTTP/1.1 代表新建user资源
DELETE /users/1 HTTP/1.1 代表删除标识符为1的user资源

第3级-超级媒体控制

超媒体控制（Hypermedia control）也被称为超媒体即应用状态引擎（Hypertext As The Engine of Application State,HATEOAS）。这个复杂的缩写词背后，蕴含着RESTful服务最重要的特性：通过使用超链接文本，可以进行服务的发现。这实际上就是告诉客户端其可选功能

如:github API

状态码

状态码必须精确

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。
HTTP 状态码就是一个三位数，分成五个类别。

• 1xx：相关信息
• 2xx：操作成功
• 3xx：重定向
• 4xx：客户端错误
• 5xx：服务器错误

2xx 状态码

200状态码表示操作成功，但是不同的方法可以返回更精确的状态码。

• GET: 200 OK
• POST: 201 Created
• PUT: 200 OK
• PATCH: 200 OK
• DELETE: 204 No Content

服务器回应

API 返回的数据应该是一个JSON格式，发生错误时，不要返回 200 状态码
如：

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

相关链接

• 阮一峰 RESTful