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：指定筛选条件

七 状态码

  • 服务器向用户返回的状态码和提示信息

    img

八 错误处理

  • 返回值携带错误的信息

    状态码为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"
}}
posted @ 2018-12-16 22:42  云丛  阅读(248)  评论(0)  编辑  收藏  举报