RESTful规范
RESTful规范
RESTful
- 是一种软件的架构风格,设计风格,为客户端和服务端的交互提供一组软件原则和约束条件
- 如果一个架构符合REST的约束和原则,我们就称它为RESTful架构
- REST是Representational State Transfer的简称,中文翻译为“表征状态转移”
restfull的规范
- 前言: 这只是一种规范,我们要尽量的满足,当需求和规范有冲突的时候,我们可以不遵守规范
一 协议
- API与用户的通信协议,总是使用https协议
二 域名
-
应该尽量的将API部署在专用的域名之下
https://api.example.com
注意:这种情况会存在跨域的问题
-
如果确定API很简单,不会进一步扩展,可以考虑放在主域名下
https://example.org/api/
这样就不会存在跨域问题
三 版本(Versioning)
-
应该将API的版本号放入URL
https://api.example.com/v1/
-
还有一种是放在请求头内
四 路径
-
在 RESTful框架中,每个网址都是一种资源,所以我们要尽最大可能的使用名词,可以是复数
https://api.example.com/v1/zoos https://api.example.com/v1/animals https://api.example.com/v1/employees
五 method方法
-
对于资源的具体操作类型,根据method的不同,进行不同的操作
GET :从服务器取出资源(一项或多项) POST :在服务器新建一个资源 PUT :在服务器更新资源(客户端提供改变后的完整资源) PATCH :在服务器更新资源(客户端提供改变的属性) DELETE :从服务器删除资源
-
实例
GET /zoos:列出所有动物园 POST /zoos:新建一个动物园 GET /zoos/ID:获取某个指定动物园的信息 PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息) PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息) DELETE /zoos/ID:删除某个动物园 GET /zoos/ID/animals:列出某个指定动物园的所有动物 DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
六 过滤信息(Filtering)
-
通过在url上传参的形式传递搜索条件
https://api.example.com/v1/zoos?limit=10:指定返回记录的数量 https://api.example.com/v1/zoos?offset=10:指定返回记录的开始位置 https://api.example.com/v1/zoos?page=2&per_page=100:指定第几页,以及每页的记录数 https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序 https://api.example.com/v1/zoos?animal_type_id=1:指定筛选条件
七 状态码
-
服务器向用户返回的状态码和提示信息
八 错误处理
-
返回值携带错误的信息
状态码为4xx是,应该返回错误信息
{ ``error: ``"Invalid API key" }
九 返回结果
-
针对不同的操作,服务器向于洪返回的结果应该符合以下规范
GET ``/``collection:返回资源对象的列表(数组) GET ``/``collection``/``resource:返回单个资源对象 POST ``/``collection:返回新生成的资源对象 PUT ``/``collection``/``resource:返回完整的资源对象 PATCH ``/``collection``/``resource:返回完整的资源对象 DELETE ``/``collection``/``resource:返回一个空文档
十 Hypermedia API
-
RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。
{``"link"``: { ``"rel"``: ``"collection https://www.example.com/zoos"``, ``"href"``: ``"https://api.example.com/zoos"``, ``"title"``: ``"List of zoos"``, ``"type"``: ``"application/vnd.yourformat+json" }}