RESTful API 规范 v1.0

本文作者：IMWeb 梁伟盛 原文出处：IMWeb社区 未经同意，禁止转载

RESTful API 规范 v1.0

toc

URI

URI规范

• 不要用大写
• 单词间使用下划线'_'
• 不使用动词，资源要使用名词复数形式，如：user、rooms、tickets
• 层级 >= 三层，则使用'?'带参数 users/1/address/2/citys (bad) /citys?users=1&address=2; (good)

Request

Method

• GET：查询资源
• POST：创建资源
• PUT/PATCH

- PUT：全量更新资源（提供改变后的完整资源）
- PATCH：局部更新资源（仅提供改变的属性）DELETE：删除资源

安全性与幂等性

• 安全性：任意多次对同一资源操作，都不会导致资源的状态变化
• 幂等性：任意次对同一资源操作，对资源的改变是一样的 |Method|安全性|幂等性| |------|:---:|:---:| |GET|√|√| |POST|×|×| |PUT|×|√| |PATCH|×|√| |DELETE|×|√|

兼容

很多客户只支持GET/POST请求，一般有两种方式模拟PUT等请求

• 添加_method参数 /users/1?_method=put&name=111
• 添加X-HTTP-Method-Override请求头 (我们使用这种方式) X-HTTP-Method-Override: PUT

参数

Method

GET

• 非id的参数使用'?'方式传输 /users/1?state=closed POST、PATCH、PUT、DELETE
• 非id的参数使用body传输，并且应该encode

过滤

?type=1&state=closed

排序

• +升序，如?sort=+create_time，根据id升序
• -降序，如?sort=-create_time，根据id降序

分页

?limit=10&offset=10

• limit：返回记录数量
• offset：返回记录的开始位置

单参数多字段

使用, 分隔，如

    /users/1?fields=name,age,city

版本控制

三种方案：

1. 在uri中加入版本： /v1/room/1
2. Accept Header：Accept: v1
3. 自定义 Header：X-Imweb-Media-Type: imweb.v1 (我们使用此方案)

自定义Media-Type参考资料github

状态码

成功

客户端错误

服务器错误

以上是常见的状态码，完整的状态码列表在这状态码

HATEOAS

在介绍HATEOAS之前，先介绍一下REST的成熟度模型

在介绍 HATEOAS 之前，先介绍一下 Richardson 提出的 REST 成熟度模型。该模型把 REST 服务按照成熟度划分成 4 个层次：

• 第一个层次（Level 0）的 Web 服务只是使用 HTTP 作为传输方式，实际上只是远程方法调用（RPC）的一种具体形式。
• 第二个层次（Level 1）的 Web 服务引入了资源的概念。每个资源有对应的标识符和表达。
• 第三个层次（Level 2）的 Web 服务使用不同的 HTTP 方法来进行不同的操作，并且使用 HTTP 状态码来表示不同的结果。如 HTTP GET 方法来获取资源，HTTP DELETE 方法来删除资源。
• 第四个层次（Level 3）的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。

简述

HATEOAS（Hypermedia as the engine of application state）是 REST 架构风格中最复杂的约束，也是构建成熟 REST 服务的核心。它的重要性在于客户端和服务器之间的解耦。

例子

分页

request请求，查询user，每页显示10条，从第10条开始显示（第二页）

    /users?limit=10&offset=10

response

    {
        data: {
            xxxx
        },
        meta: {
            _link: [
                {rel: 'self', href: 'xxx/users?limit=10&offset=10'},
                {rel: 'first', href: 'xxx/users?limit=10&offset=0', title: 'first page'},
                {rel: 'last', href: 'xxx/users?limit=10&offset=50', title: 'last page'},
                {rel: 'prev', href: 'xxx/users?limit=10&offset=0', title: 'prev page'},
                {rel: 'next', href: 'xxx/users?limit=10&offset=20', title: 'next page'}
            ]
        }    
    }

_link返回了5个资源

• rel: 'self'，资源本身
• rel: 'first'，第一页资源
• rel: 'last'，最后一页资源
• rel: 'prev'，上一页资源
• rel: 'next'，下一页资源

权限相关

如用户查询一个订单

普通用户

request

    /orders/1

response

    {
        data: {
            xxx
        },
        meta: {
            _link: [
                {rel: 'self', href: 'xxx/orders/1'},
                {rel: 'related', href: 'xxx/orders/1/payment', title: 'pay the order'}
            ]
        }
    }

_link返回两个资源

• rel: 'self'，资源本身
• rel: 'related'，与当前资源相关的资源，/order/1/payment用户可以使用此资源进行支付

权限用户

request

    /orders/1

response

    {
        data: {
            xxx
        },
        meta: {
            _link: [
                {rel: 'self', href: 'xxx/orders/1'},
                {rel: 'edit', href: 'xxx/orders/1', title: 'edit the order'},
                {rel: 'delete', href: 'xxx/orders/1', title: 'delete the order'}
            ]
        }
    }

此用户拥有修改与删除订单的权限，因此返回了3个资源

• rel: 'self'，资源本身
• rel: 'edit'，此用户可修改该资源
• rel: 'delete'，此用户可删除该资源

常用rel

HATEOAS总结

由以上例子可以看出_link就是以Hyperlink表述资源与资源之间的关系，这种方式使客户端与服务端能很好的分离开来，只要接口的定义不变，客户端与服务端就可以独立的开发和演变。