restful规范
1 .根据method的不同执行不同的操作:
- GET (SELECT):从服务器检索特定资源,或资源列表。
- POST (CREATE):在服务器上创建一个新的资源。
- PUT (UPDATE):更新服务器上的资源,提供整个资源。
- PATCH (UPDATE):更新服务器上的资源,仅提供更改的属性。
- DELETE (DELETE):从服务器删除资源。
2.API尽量采用通过安全通道的HTTPS协议(https)
3.域名
4.版本
- 放在URL上:https://example.org/api/v1/
- 放在请求头上
5.路径
尽量使用名词(可以是复数)
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:删除某个指定动物园的指定动物
6.过滤,通过在url上传参的形式搜索条件
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page_number=2&page_size=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,
GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
7.状态码(code)
https://baike.baidu.com/item/HTTP状态码/5053660?fr=aladdin
8.返回结果集
针对不同操作返回不同的结果
9.返回错误信息
10.Hypermedia API
即返回结果中提供连接,连向其他API方法