RESTful API的理解

killmice 2019-06-25

RESTful API

目前的异步加载横行的时候,异步请求已经遍地都是,而规定请求接口的时候,如果不能有很好的风格的话,很多时候会让开发者误解,一个好的API接口 设计需要注意以下:

  1. 参数职责单一
  2. 意图清晰,便于开发者调用
  3. 易于访问者输入

看是但是真的设计的时候经常会设计出不规范 的接口,

REST原则

REST 即Representational State Transfer的缩写。它的理论比较抽象不太具体,理解它主要在于理解这些概念:资源、表现层、状态转换。
基于REST原则设计的API,一般称为 RESTFul API,需要遵守以下这些原则。

  1. URL描述的是一个特定资源。因此描述需要名词,不能出现动词。因为动词描述的不再是资源本身,而是行为
  2. 利用HTTP请求的动词表示对于资源操作的行为

同时,对于URL的设计一般还有约定俗成的以下补充。

  1. 对于资源的描述的名词应该是层级嵌套的方式,比如 /company/department/projects。通过这种对于信息层级描述的方式,更利于实体的抽象,以及增加客户端与服务器端开发人员对于整个系统模块认知的一致性
  2. 路径终点的命名考虑用复数形式,比如 /books。一般一个URL路径表示的资源会映射为数据库一系列表的记录的集合,因此使用复数更直观

实践设计

实际设计restful api时的注意点包括以下:

  1. 尽量使用https协议
  2. 如果接口是公用且会被扩展时,应该考虑放在专有域名下,https://api.baidu.com
  3. 由于api会在业务中不断地迭代,所以最好是带上版本,https://api.baidu.com/v2/
  4. 最后接口路径应该尽量使用集合,也就是复数形式,https://api.baidu.com/v2/books
  5. 操作类接口应该注意使用对应的动词来操作

    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:删除某个指定动物园的指定动物
  6. 参数,使用参数来进行筛选,?page=2&per_page=100:指定第几页,以及每页的记录数。
  7. 返回结果,结果应该包括多种情况,异常、错误信息、正确结果{status:'ok',massage:'ok',data:{data:1}}
  8. 目前而言最好使用JSON格式传输数据。

参考:efe的restful理解阮一峰restful api

相关推荐