REST API设计规范
REST API
REST API被建模为可单独寻址的资源的集合，资源可以通过名称引用，并通过一组方法进行操作。以下规范参考REST Google API的设计方法。
设计流程
- 1、确定API提供的资源类型
- 2、确定资源之间的关系
- 3、基于资源的类型和关系确定资源的命名方式
- 4、确定资源模式
- 5、确定资源的最小化方法集
资源
一个面向资源的API通常是按资源层级来建模的，各层级节点被称为资源或者集合。
- 一个集合包含一组相同类型的资源。
- 一个资源会有一些状态，或者拥有几个子资源。
资源ID
识别父资源中资源的非空URI段。
集合ID
识别父资源中集合资源的非空URI段。
资源命名
在面向资源的API中，资源被命名为实体，其中资源名是它们的标识符。每个资源都有自己的资源名，资源名由资源本身的ID、父资源的ID和它的API服务名组成。
集合是一种特殊类型的资源，它包含相同类型的子资源列表，例如
| API | 集合ID | 资源ID |
|---|---|---|
| //storage.moneymeow.com | /users | /user-id |
方法
面向资源的API的关键特性是它强调资源，而不是在资源上执行的方法。一个面向资源的API使用少量方法操作大量资源。
标准方法
- List：将一个集合名称和零个或多个参数作为输入，并返回与输入匹配的资源列表。通常用于搜索资源，适用于单个集合的数据。
- Get：将一个资源名称、零个或多个参数以及资源的返回值说明作为输入。
- Create：将一个集合名称、一个资源名称和零个或多个参数作为输入，在指定集合中创建一个新资源，并返回新创建的资源。
- Update：将一个资源名称和零个或多个参数作为输入，更新指定的资源及其属性，并返回更新的资源。
- Delete：将一个资源名称和零个或多个参数作为输入，删除指定的资源，并返回空值。
错误码
| HTTP | RPC | 描述 |
|---|---|---|
| 200 | OK | 正常 |
| 400 | INVALID_ARGUMENT | 客户端指定了无效参数 |
| 400 | FAILED_PRECONDITION | 请求无法再当前系统状态下执行 |
| 400 | OUT_OF_RANGE | 越界 |
| 401 | UNAUTHENTICATED | 未通过身份验证 |
| 403 | PERMISSION_DENIED | 客户端没有足够的权限 |
| 404 | NOT_FOUND | 指定资源未被发现或请求被拒绝 |
| 409 | ABORTED | 并发冲突 |
| 409 | ALREADY_EXISTS | 客户端尝试创建的资源已存在 |
| 429 | RESOURCE_EXHAUSTED | 资源配额达到限制速率 |
| 499 | CANCELLED | 请求被取消 |
| 500 | DATA_LOSS | 不可恢复的数据丢失或损坏 |
| 500 | UNKNOWN | 未知的服务器错误 |
| 500 | INTERNAL | 内部服务器错误 |
| 501 | NOT_IMPLEMENTED | API方法未由服务器实现 |
| 503 | UNAVALIABLE | 服务不可用 |
| 504 | DEADLINE_EXCEEDED | 请求超时 |