REST FULL 笔记

Posted on | Edited on | In

这里是一个简单的 RESTful api 的例子.

参考:

阮一峰的网络日志: RESTful API 设计指南

阮一峰的网络日志: 理解RESTful架构

主要用 Plurar 复数

这里我们用一个现实的例子, 获取连锁超市的物品和员工

url 设计:

在主域名下挂个 api 子域名

https://api.example.com

或者

https://example.com/api

Api 版本

https://api.example.com/v1/

路径 (endpoint)

路径我们采用复数 (item => 单数，items => 复数)

1
2
3
4
5
6
7
8
9
获取,更改,删除多个资源
https://api.example.com/v1/supermarkets
https://api.example.com/v1/products
https://api.example.com/v1/employees

获取,更改,删除某个资源
https://api.example.com/v1/supermarkets/id
https://api.example.com/v1/products/id
https://api.example.com/v1/employees/id

HTTP 方法

GET: 获取资源 返回资源
POST: 创建资源 返回资源
PUT: 更新资源 返回资源
DELETE: 删除资源 返回 http status 200 (处理成功的意思).

HTTP 状态

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。

  • 202 Accepted：表示一个请求已经进入后台排队（异步任务).

  • 204 NO CONTENT - [DELETE]：用户删除数据成功。

  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作.

  • 401 Unauthorized：表示用户没有权限（令牌、用户名、密码错误）。

  • 403 Forbidden:表示用户得到授权（与401错误相对），但是访问是被禁止的。

  • 404 NOT FOUND: 用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。

  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。

  • 500 INTERNAL SERVER ERROR：服务器发生错误，用户将无法判断发出的请求是否成功