API规范

规范

Created At : 2020-04-03 22:33

Views 👀 :

Comment:

API规范
1. 简介
2. 规则
参考
1. 网站
2. github网站页面的部分API参考

API规范

简介

RESTful API是目前比较成熟的一套互联网应用程序的API设计理论,它遵循资源导向的设计方式。
它有三个主要要素：资源，集合和 URLs。
- 资源具有数据，嵌套，和一些操作方法。
- 一组资源称为一个集合。
- URL标识资源或集合的线上位置。

规则

命名规则

使用kebab-case（短横线分割）的URL

例子：/api/be/project-config

在查询字符串或资源字段中使用camelCase模式。

例子：/api/be/meeting-config/projectUid=1453

URLs里面请尽量少用动词

因为如果您为每个资源操作使用一个动词，您很快就会维护一个很大的URL列表，而且没有一致的使用模式，这会使开发人员难以学习。此外，我们还要使用动词做别的事情。
错误例子：/api/be/project-config/create/list
/api/be/project-config/users/addName

为非资源型请求使用动词。在这种情况下，您的API并不需要返回任何资源。而是去执行一个操作(除CRUD操作）并返回执行结果。

例子：/api.github.com/_private/browser/star 点赞操作

资源命名区分单复数

文档(Document)类型的资源用名词(短语)单数命名（如一篇文章https://api/article）
集合(Collection)类型的资源用名词(短语)复数命名（如文章列表https://api/articles）

操作表示

HTTP方法来操作CRUD功能

GET: 查询—–查询资源
POST: 创建—-创建一些新的资源或者子资源
PUT: 更新全部—-更新一个存在的资源（提供全部信息）
PATCH: 更新部分—-更新现有资源。它只更新所提供的字段，不管其他字段
DELETE: 删除—–删除一个存在的资源

例子：

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：删除某个指定动物园的指定动物

附：pacth与put的区别
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?producy_type=1：指定筛选条件

关系表示

对于嵌套资源，在URL体现关系。同时避免层级过深。
例如，使用id将员工与公司联系起来。

GET /schools/2/students , 应该从学校2得到所有学生的名单
GET /schools/2/students/31 , 应该得到学生31的详细信息，且此学生属于学校2
DELETE /schools/2/students/31 , 应删除属于学校2的学生31
PUT /schools/2/students/31, 应该更新学生31的信息
POST /schools , 应该创建一所新学校，并返回创建的新学校的细节。在集合URL上使用POST

但是如 GET /zoos/1/areas/3/animals/4
尽量使用查询参数代替路径中的实体导航，如GET/animals?zoo=1&area=3

附：post请求和get请求的区别
如有迭代版本（v1,v2,v3），使用简单的序数表示版本。并将其移到URL的左侧，使其具有最高的范围表述：

http://api.domain.com/v1/schools/3/students

其他

Response不要包装，body 直接就是数据，

错误例子：{ "success":true， "data":{"id":1,"name":"xiaotuan"}, }
Service/DAO层方法命名规约

1) 获取单个对象的方法用get做前缀。
2) 获取多个对象的方法用list做前缀。
3) 获取统计值的方法用count做前缀。
4) 插入的方法用save/insert做前缀。
5) 删除的方法用remove/delete做前缀。
6) 修改的方法用update做前缀。

参考

网站

github网站页面的部分API参考

https://github.com/ant-design/ant-design

请求star数量 https://api.github.com/_private/browser/stats
用户资料卡 https://github.com/hovercards?user_id=7264444&subject=33
star https://github.com/ant-design/ant-design/star
unstar https://github.com/ant-design/ant-design/unstar
Issues功能 https://github.com/ant-design/ant-design/issues?_pjax=%23js-repo-pjax-container
查询功能 https://github.com/ant-design/ant-design/search/count?q=d%27d%27d&type=Commits&unscoped_q=d%27d%27d
更新设置 https://github.com/newsletter_preference

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 1249118795@qq.com