欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

RESTful API接口设计风格

程序员文章站 2024-03-25 16:50:04
...

REST API(表现层状态转化)

  • 简单理解为:URL定位资源,用HTTP动词(GET,POST,DELETE,PUT)描述操作。
说明

(1)每一个URI代表一种资源;
(2)客户端和服务器之间,传递这种资源的某种表现层;
(3)客户端通过四个HTTP动词,对服务器端资源进行操作,实现"表现层状态转化"。

规范的问题
  • 因为多人开发时,会导致处理请求方式(get、post乱用),接口不统一(接口名写法千差万别),会导致各种状况都有,后期维护是个大问题,再就是请求方式也不对。
  • 所以RESTFUL API的结构设计就诞生了
  1. 接口命名规范
    域名:

    //将api部署在专用域名下:
    http://api.example.com
    / /或者将api放在主域名下:
    http://www.example.com/api/
    

    版本:

    将API的版本号放在url中。
    http://www.example.com/app/1.0/
    http://www.example.com/app/1.2/
    

    路径:

    路径表示API的具体网址。每个网址代表一种资源。 
    资源作为网址,网址中不能有动词只能有名词,一般名词要与数据库的表名对应。
    一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
    http://www.example.com/app/1.0/lists
    http://www.example.com/app/1.0/names
    
  2. 使用标准的HTTP方法

    使用标准的HTTP方法:对于资源的具体操作类型,由HTTP动词表示。 常用的HTTP动词有四个。

    GET     :从服务器取出资源(一项或多项)
    POST    :在服务器新建资源。
    PUT     :在服务器更新资源。
    DELETE  :从服务器删除资源。
    

    过滤信息

    如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
    eg:
    ?limit=10:指定返回记录的数量
    ?page=2&per_page=100:指定第几页,以及每页的记录数。
    ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
    ...
    
示例:
  • 一个URl实现增删改查所有操作,具体靠http请求头部信息判断
//CRUD(增删改查) 操作学生用户的接口 /rest/1.0/userinfo

//增加一个id为1的用户    
post           /rest/1.0/userinfo           data: {id:1,name:'张三'}
//删除id为1的用户           
delete         /rest/1.0/userinfo?id=1
//修改id为1的用户           
put            /rest/1.0/userinfo?id=1      data:{id:1,name:'李四'}
//查询所有用户           
get            /rest/1.0/userinfo
//查询id为1的用户信息 
get            /rest/1.0/userinfo?id=1

转载于:https://www.jianshu.com/p/64cca3ebbef8