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  云丛  阅读(261)  评论(0编辑  收藏  举报