RESTful 服务和 HTTP 操作谓词的基础知识

Restful的本质

一种基于资源的软件架构风格.

核心

面向资源设计API

解决的问题

1. 降低开发的复杂性

2. 提供系统的可伸缩性

3. 只需设计一套相同的后端处理接口，就可以为不同类型的终端（PC、Mobile等）提供服务。

设计概念和准则

1. 网络上的所有事物都可以被抽象为资源；
2. 每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识；
3. 所有的操作都是无状态的（每次操作都是独立的，互不关联）

资源

网络上的一个实体，或网络上的一个具体信息（文字、图片、视频、音频等）。

Restful API
从定义上来说，Restful与http协议无关，但Restful API是基于http协议的一种实现，所有相关知识都是基于现有http协议而来，并没有对http协议进行扩充。

http协议-url
http是一个属于应用层的协议，特点是简捷、快速。

一个完整的url组成形式：
schema://host[:port]/path[?query-string][#anchor]

scheme 指定底层使用的协议(例如：http,https,ftp)
host 服务器的IP地址或域名
port 服务器端口,默认为80；https的默认端口是443
path 访问资源的路径（标识主机中的所有资源）
query-string 发送给http服务器的数据（查询字符串，一般用于对资源做筛选操作）
anchor 锚（直接滚动到当前页面的某个区域）
http协议-请求
组成格式：请求行、消息报头、请求报文

请求行
格式如下：Method Request-URL HTTP-Version CRLF
Method ：请求方法
Request-URL ：请求地址
HTTP-Version ：http协议版本号
CRLF ：回车换行
举例
GET / HTTP/1.1 CRLF （请求主机根目录下资源的请求头）
请求成功，则返回资源内容。

请求方法

GET 请求获取Request-URL所标识的资源；（获取资源）
POST 在Request-URL所标识的资源后附加新的数据；（发送数据）
HEAD 请求获取由Request-URL所标识的资源的响应消息报头；
PUT 请求服务器存储一个资源，并用Request-URL作为其标识；（更新资源时使用）
DELETE 请求服务器删除Request-URL所标识的资源；
OPTIONS 请求查询服务器的性能,或者查询与资源相关的选项和需求；（访问频率限制参数）
http协议-响应
组成格式：状态行、消息报头、响应正文

状态行
HTTP-Version Status-Code Reason-Phrase CRLF

HTTP-Version ：http协议版本号
Status-Code ：响应状态码
Reason-Phrase ：字面的响应内容
CRLF：回车换行
例如：HTTP /1.1 200 OK

常用状态码

200 OK //客户端请求成功 （客户端请求成功，且服务端响应成功）
400 Bad Request //客户端请求有语法错误，不能被服务器所理解
401 Unauthorized //服务器收到请求,但是拒绝提供服务（请求的资源需要授权访问，但客户端并未授权）
404 Not Found //请求资源不存在
一般来说，以5开头的状态码都是服务器内部错误
500 Internal Server Error //服务器发生不可预期的错误（服务器程序错误）
503 Server Unavailable //服务器当前不能处理客户端的请求（服务器性能达到瓶颈时，拒绝后续服务）
Restful架构与其他架构的区别（了解）
SOAP WebService
WebService 跨编程语言和跨操作系统平台的远程调用技术。
略…

如何设计Restful API（Restful设计要素）
资源路径（URI）：设计资源路径；
HTTP动词：即请求方式；

1. 过滤信息：获取资源列表时的分页操作，或普通的查询操作都要用到过滤信息，此时要合理分配过滤信息，避免过滤信息过多，违反Restful规定；
2. 状态码：服务端在客户端发送请求后，其应返回的响应状态码； 错误处理：服务端在发现客户端传入的参数错误时，应该返回的信息；
3. 返回结果：
   POST操作后，需要返回资源实例；
   GET资源列表时，需要返回资源数组。
   资源路径 , 在Restful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。
   一般来说API中的名词应该是复数。

API的版本号问题：

处理方式1：将API的版本号加入到资源的地址中。
处理方式2：将API的版本号加入到HTTP请求头中。
HTTP动词
对资源的操作（CURD），由HTTP动词（谓词）表示。

 1. GET ：从服务器取出资源（一项或多项）。 
 2. POST ：在服务器新建一个资源。 
 3. PUT    ：在服务器更新资源（客户端提供改变后的完整资源）。（返回整个资源的信息）
 4.  DELETE ：从服务器删除资源。 
 5. PATCH    ：在服务器更新资源（客户端提供改变的属性）。（只返回更新的属性）

过滤信息
如果记录数很多，服务器不可能将它们都返回给用户。
筛选操作前，API应该提供参数，过滤返回的结果。

状态码
服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。

200 OK 服务器成功返回用户请求的资源，该操作是幂等的。

204 NO CONTENT 删除数据成功（无响应体）。

400 Bad Request 用户发出的请求有错误，该操作是幂等的。

401 Unauthorized 表示用户没有认证，无法进行当前操作（用户未提供认证选项或参数）。

403 Forbidden 表示用户访问是被禁止的。（用户提供了认证参数，但可能认证参数错误，或无权限）。

422 Unprocesable Entity 当创建一个对象时，发生一个验证错误（验证信息不全）。

500 Internal Server Error /服务器发生错误，用户将无法判断发出的请求是否成功。

错误处理
配合HTTP状态码。如果状态码是4XXX 或 5XXX，就应该向用户返回出错信息，信息如下。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
“error”:“参数错误”
}
返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范：

 1. GET/collections：返回资源对象的列表（数组）
 2.  GET/collections/identity：返回单个资源对象,  如果资源不存在，返回404状态码；
 3.  POST/collections：返回新生成的资源对象（返回新创建的资源的全部属性）
 4.     PUT/collections/identity：返回完整的资源对象（返回被更新资源的完整属性）
 5.     PATCH/collections/identity：返回被修改的属性
 6.     DELETE/collections/identity：返回一个空文档  删除了资源，要返回204状态码。