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"
  }}