api接口restful风格通用规范

lv_suming
1,433 阅读4分钟

  • api与用户通信建议使用https

  • url规范——通过url方式来区分
    前端使用www.fandx.com
    后端使用www.fandx.com/api

  • 版本
    www.fandx.com/api/v1/

  • 接口命名（使用名词）
    www.fandx.com/api/v1/name/:value

  • method形式
    get 查询
    post 添加
    put 在服务器更新资源（客户端提供改变后完整的资源）
    patch 在服务器更新资源 （客户端提供改变的属性）
    delete 从服务器删除资源

  • 过滤，通过url传参的方式传递查询条件(所有查询条件都放在?后面以参数形式传递)
    ?limit=10 指定返回记录的数量
    ?offset=10 指定返回记录的开始位置
    ?page=2&size=100 指定第几页，以及每一页记录数
    ?sortby=name&order=asc 指定返回结果按照哪个属性排序，以及排序顺序
    ?animal_type_id =1 指定筛选条件

  • 状态码
    200 成功
    300 重定向
    400 客户端错误
    401 用户没有权限令牌
    403 用户得到授权，但是访问是被禁止的
    404 访问的资源找不到
    500 服务器内部错误

  • 错误返回建议error当做key

  • 返回结果
    get /collection 返回资源列表
    get /collection/resource 返回单个资源对象
    post /collection 返回新生成的资源对象
    put /collection/resource 返回完整的资源对象
    patch /collection/resource 修改局部，返回完整的资源对象
    delete /collection/resource 返回一个空文档

  • 正确示例

    http(s): //server.com /app-name /{version} /{domain} /{rest-convention}

    {version}代表api的版本信息。
    {domain}是一个你可以用来定义任何技术的区域(例如：安全-允许指定的用户可以访问这个区域)或者业务上的原因(例如：同样的功能在同一个前缀之下。)
    {rest-convention} 代表这个域(domain)下，约定的rest接口集合。

    单资源(singular-resourceX)
    url样例：order/ (order即指那个单独的资源X)
    GET – 返回一个新的order
    POST- 创建一个新的order，从post请求携带的内容获取值。

    单资源带id(singular-resourceX/{id})
    URL样例：order/1 (order即指那个单独的资源X)
    GET – 返回id是1的order
    DELETE – 删除id是1的order
    PUT – 更新id是1的order，order的值从请求的内容体中获取。

    复数资源(plural-resourceX/)
    URL样例:orders/
    GET – 返回所有orders

    复数资源查找(plural-resourceX/search)
    URL样例：orders/search?name=123
    GET – 返回所有满足查询条件的order资源。(实例查询，无关联) – order名字等于123的。

    复数资源查找(plural-resourceX/searchByXXX)
    URL样例：orders/searchByItems?name=ipad
    GET – 将返回所有满足自定义查询的orders – 获取所有与items名字是ipad相关联的orders。

    单数资源(singular-resourceX/{id}/pluralY)
    URL样例：order/1/items/ (这里order即为资源X，items是复数资源Y)
    GET – 将返回所有与order id 是1关联的items。

    singular-resourceX/{id}/singular-resourceY/
    URL样例：order/1/item/
    GET – 返回一个瞬时的新的与order id是1关联的item实例。
    POST – 创建一个与order id 是1关联的item实例。Item的值从post请求体中获取。

    singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/
    URL样例：order/1/item/2/package/
    GET – 返回一个瞬时的新的与item2和order1关联的package实例。
    POST – 创建一个新的与item 2和order1关联的package实例，package的值从post请求体中获得。

    上面的规则可以在继续递归下去，并且复数资源后面永远不会再跟随负数资源。
    总结几个关键点，来更清晰的表述规则。

    在使用复数资源的时候，返回的是最后一个复数资源使用的实例。
    在使用单个资源的时候，返回的是最后一个单个资源使用的实例。
    查询的时候，返回的是最后一个复数实体使用的实例(们)。

  • 其他规范：
    规则1：URI结尾不应包含（/）
    规则2：正斜杠分隔符（/）必须用来指示层级关系
    规则3：应使用连字符（ - ）来提高URI的可读性
    规则4：不得在URI中使用下划线（_）
    规则5：URI路径中全都使用小写字母

avatar
文章
阅读
粉丝