REST¶

特征¶

客户端 <--> 服务端：客户端与服务端有明确的界限
无状态：服务器不能在两次请求之间保存客户端的任何状态
缓存：服务器发出的响应可以标记为可缓存或不可缓存，这样出于优化的目的，客户端（或客户端和服务器之间的中间服务）可以使用缓存
接口统一：客户端访问服务器资源时使用的协议必须一致、定义良好，且已经标准化
系统分层：在客户端和服务器之间可以按需插入代理服务器、缓存或网关，以提高性能、稳定性和伸缩性。
按需编程：客户端可以选择从服务器中下载代码，在客户端的上下文中执行。

资源就是一切¶

资源是 REST 架构风格的核心概念，资源是应用中需要被着重关注的事物，每一个资源都是用唯一的 URL 表示，对 HTTP 协议来说，资源的标示符是 URL，

某一类资源的集合可以有一个 URL，如 /api/users/,
某一个用户可以是/api/user/1234，1234 是用户的唯一标识符，使用用户在数据库中的主键表示。

请求与响应¶

请求方法¶

请求方法	目标	说明	HTTP 状态码
GET	单个资源的 URL	获取目标的资源	200
GET	资源集合的 URL	获取资源的集合（也可以获取分页中的一页资源）	200
POST	资源集合 URL	创建新的资源，并加入目标集合，服务器为新的资源指派 URL，并在响应的 Location 头部中返回	201
PUT	单个资源的 URL	修改一个现有的资源，如果客户端能为资源指派 URL，也可以用来创建新的资源	200/204
DELETE	单个资源的 URL	删除一个资源	200/204
DELETE	资源集合的 URL	删除目标集合中的所有资源	200/204
PATCH
HEAD
OPTIONS

HTTP 状态码¶

HTTP状态码	名称	说明
200	OK（成功）	请求成功
201	Created（已创建）	请求成功，而且创建了一个新资源
202	Accepted（已接收）	请求已接收，但仍在处理中，将异步处理
204	No Content（没有内容）	请求成功处理，但是返回的响应没有数据
400	Bad Request（坏请求）	请求无效或不一致
401	Unauthorized（未授权）	请求未包含身份验证信息，或者提供的凭据无效
403	Forbidden（禁止）	请求中发送的身份验证凭据无权访问目标
404	Not Found（未找到）	URL 对应的资源不存在
405	Method Not Allowed（不允许使用的方法）	指定资源不支持请求使用的方法
500	Internal Server Error（内部服务器错误）	处理请求的过程中发生意外错误

请求与响应主体¶

在请求和响应的主体中，资源在客户端和服务器之间来回传送，但 REST 没有指定编码资源的方式。请求和响应中的 Content-Type 首部用于指明主体中资源的编码方式。使用 HTTP 协议的内容协商机制，可以找到一种客户端和服务器都支持的编码方式。

常用的两种编码方式：

JSON
XML

JSON 相比 XML 更加简洁并且与 JavaScript 联系紧密

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

{
  "self_url": "http://a.b.c.com/api/books/1234",
  "title": "",
  "author_url": "",
  "comments_url":""
}

版本¶

使用版本来区分 Web 处理的 URL 来保持对旧版本的客户端兼容，比如 /api/v1/books/

认证¶

HTTP Basic auth¶

REST 式 Web 服务的特征之一是无状态，即服务器在两次请求之间不能“记住”客户端的任何信息。客户端必须在发出的请求中包含所有必要信息，因此所有请求都必须包含用户凭据。（无状态的服务器伸缩起来更加简单。如果服务器保存了客户端的相关信息，那么必须保证特定客户端发送的请求由同一台服务器处理，或者使用共享存储器存储客户端数据。这两点都难以实现，但是如果服务器是无状态的，这两个问题也就不复存在。）

由于 REST 是基于 HTTP 协议，所以发送凭证最简单的方式是使用 HTTP 身份认证，基本验证/摘要认证，在 HTTP 身份验证中，用户凭据包含在每一个请求的 Authorization

Token¶

每次请求，客户端都要发送身份验证凭据。为了避免总是发送敏感信息（例如密码），我们可以使用一种基于令牌的身份验证方案。

在基于令牌的身份验证方案中，客户端先发送一个包含登录凭据的请求，通过身份验证后，得到一个访问令牌。这个令牌可以代替登录凭据对请求进行身份验证。出于安全考虑，令牌有过期时间。令牌过期后，客户端必须重新发送登录凭据，获取新的令牌。令牌短暂的使用期限，可以降低令牌落入他人之手所导致的安全隐患。为了生成和核查身份验证令牌

OAUTH2¶

序列化与反序列化¶

Web 服务把内部表示转换成传输格式的过程称为序列化。提供给客户端的资源表示没必要与数据库模型的内部定义完全一致。
序列化的逆向操作称为反序列化。把 JSON 结构反序列化成模型时面临的问题是，客户端提供的数据可能无效、错误或者多余。