RESTFUL Api学习

RESTFUL Api

推荐去Apifox的API Hub 查看各个公司的api规范

---

概念

请求设计

请求 = 动词 + 宾语

动词 使用五种 HTTP 方法，对应 CRUD 操作。

宾语 URL 应该全部使用名词复数，可以有例外，比如搜索可以使用更加直观的 search 。

过滤信息（Filtering） 如果记录数量很多，API应该提供参数，过滤返回结果。 ?limit=10 指定返回记录的数量 ?offset=10 指定返回记录的开始位置。

GET/zoos 列出所有动物园

POST/zoos 新建一个动物园

GET/zoos/:id 获取某个指定动物园的信息

PUT/zoos/:id 更新某个指定动物园的全部信息

PATCH/zoos/:id 更新某个指定动物园的部分信息

DELETE/zoos/:id 删除某个动物园

GET/zoos/:id/animals 列出某个指定动物园的所有动物

DELETE/zoos/:id/animals/:id 删除某个指定动物园的指定动物

响应设计

使用 HTTP 的状态码

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

五大类状态码，总共100多种，覆盖了绝大部分可能遇到的情况。每一种状态码都有约定的解释，客户端只需查看状态码，就可以判断出发生了什么情况。API 不需要1xx状态码。

1xx 相关信息

2xx 操作成功

3xx 重定向

4xx 客户端错误

5xx 服务器错误

服务器回应数据

客户端请求时，要明确告诉服务器，接受 JSON 格式，请求的 HTTP 头的 ACCEPT 属性要设成 application/json

服务端返回的数据，不应该是纯文本，而应该是一个 JSON 对象。服务器回应的 HTTP 头的 Content-Type 属性要设为 application/json

错误处理 如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。 {error: “Invalid API key”}

认证 RESTful API 应该是无状态，每个请求应该带有一些认证凭证。推荐使用 JWT 认证，并且使用 SSL

Hypermedia 即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么

---

案例

GET

获取某个带形容词的名词一般都通过附带参数，

1. 获取单个指定id的article

   GET /atricles/{id}

   GET /articles?id=12312

   前者为获取单篇article，后者是获取多个但筛选出id=12312的article，返回值不一样，一个是直接返回article，一个是返回[article]。

2. 获取所有articles

   GET /articles?pageSize=0

3. 获取页数为1,页面大小为5的articles list

   GET /articles?pageSize=5?page=1

4. 获取title为"HelloWorld"的article

   GET /articles?title=HelloWorld

5. 获取某个article的某个评论

   GET /articles/{id}/comments/{id}

6. 获取article的基本信息

   GET /articles?base=true

7. 获取指定id的article的基本信息

   GET /articles/{id}?base=true

8. 获取titile为"HelloWorld"的article中id为1的评论

   先获取ariticle的id

   GET /articles?title=HelloWorld

   再通过该id获取评论

   GET /articles/{id}/comments/{id}

POST

1. 登陆

   POST /session

2. 添加article

   POST /articles

DELETE

1. 退出

   DELETE /session

2. 删除article

   DELETE /articles/{id}

PUT

1. 刷新

   PUT /session

2. 修改article

   PUT /articles/{id}

参考:

1. Elasticsearch：官方分布式搜索和分析引擎 | Elastic
2. Apifox中的API Hub (推荐)