RESTful学习笔记

RESTful是什么？

它的本质是一种软件架构风格，核心是面向资源（面向资源去设计API），它解决的问题有：①降低开发的复杂性②提高系统的可伸缩性。

设计概念和准则

• 网络上所有事物都可以被抽象为资源
• 每个资源都有唯一的资源标识，对资源的操作不会改变这些标识（例如对某一资源进行删除操作，删除完成后，它的资源标识还是有效的，只不过这个资源标识代表的资源不存在了）
• 所有的操作都是无状态的（前一次操作和后一次操作没有关联）

HTTP协议

URL

HTTP是属于应用层的协议，特点是简洁、快速。

schema://host[:port]/path[?query-string][#anchor]

• scheme ：指定低层使用的协议（例如：http, https, ftp）
• host ：服务器的IP地址或者域名
• port ：服务器端口，默认为80
• path：访问资源的路径
• query-string ：发送给http服务器的数据
• anchor: 锚

请求

组成格式：请求行、消息报头、请求正文

请求行

格式：Method Request-URI HTTP-Version CRLF

• Method ：请求方法
• Request-URI：请求路径
• HTTP-Version: HTTP协议版本号

示例：GET/HTTP/1.1CRLF

请求方法

• GET ：请求获取Request-URL所标识的资源
• POST：在Request-URI所标识的资源后附加新的数据
• HEAD：请求获取由Request-URI所标识的资源的响应信息报头（比如获取资源创建时间与最后修改时间等）
• PUT：请求服务器存储一个资源，并用Request-URI作为其标识（常用于更新）
• DELETE：请求服务器删除Request-URI所标识的资源
• OPTIONS：查询服务器性能

响应

组成格式：状态行、消息报头、响应正文

状态行

格式：HTTP-Version Status-Code Reason-Phrase CRLF

例如：HTTP/1.1 200 OK

状态码

• 200 OK ：客户端请求成功
• 400 Bad Request : 客户端请求有语法错误，不能被服务器所理解
• 401 Unauthorized ：服务器收到请求，但是拒绝服务（无权限等）
• 404 Not Found ：请求资源不存在
• 500 Internal Server Error ：服务器发生不可预期的错误
• 503 Server Unavailable : 服务器当前不能处理客户端的请求（性能达到瓶颈等）

RESTful设计要素

如何设计RESTful API

资源路径（URI）

在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数。

例如：

//获取动物园资源，其中 v1 是版本号
https://api.example.com/v1/zoos

HTTP动词

对于资源的操作（CURD），由HTTP动词表示。

• GET：获取服务器资源
• POST：创建新的服务器资源
• PUT：更新完成后返回整条记录
• DELETE：删除某个服务器资源
• PATCH：更新完成后返回改变的属性

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

例如：

• ?offset=10 ：指定返回记录的开始位置
• ?sortby=name&order=asc：指定返回结果排序，以及排序顺序

状态码

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

• 200 OK：服务器成功返回用户请求的数据
• 201 CREATED ：新建或修改数据成功
• 204 NO CONTENT：删除数据成功
• 400 BAD REQUEST：用户发出的请求有错误
• 401 Unauthorized：表示用户没有认证，无法进行当前操作（没有提供认证参数）
• 403 Forbidden：表示用户访问是被禁止的（权限不足或认证参数错误等）
• 422 Unprocesable：当创建一个对象时，发生一个验证错误（创建新资源时，未提供所有所需字段等）
• 500 INTERNAL SERVER ERROR ：服务器发生错误，用户无法判断发出的请求是否成功

错误处理

如果状态码是4XX或者5XX ，就应该向用户返回出错信息。一般来说，返回信息中将error作为键名，出错 信息作为键值即可：

{
    "error" : "参数错误"
}

返回结果

针对不同的操作，服务器向用户返回的结果应该符合以下规范：

• GET /collections ：返回资源对象的列表（数组）
• GET /collections/identity ：返回单个资源对象
• POST /collections ：返回新生成的资源对象
• PUT /collections/identity：返回完整的资源对象
• PATCH /collections/identity ：返回被修改的属性
• DELETE/collections/identity ：返回一个空文档