RESTful规范 GET请求、POST请求、PUT请求、DELETE请求的使用规范
RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。
RESTFul规范：
一．http动词：
GET（SELECT）：从服务器取出资源（一项或多项）
POST（CREATE）：在服务器新建一个资源(动作类：无法用http动词表示的)
PUT（UPDATE）：在服务器更新资源
DELETE（DELETE）：从服务器删除资源
二. 资源：
所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实体。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。
三．误区：
1.最常见的一种设计错误，就是URI包含动词
RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show。
2.资源 ！= 表
如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：POST /accounts/1/transfer/500/to/2
正确的写法是把动词transfer改成名词transactions，资源不能是动词，但是可以是一种服务：POST /accounts/transactions HTTP/1.1 from=1&to=2&amount=500.00（动词若没有名词形式，则直接使用动词加s）
四．命名原则:
URI命名通常有三种，驼峰命名法(serverAddress)，蛇形命名法(server_address)，脊柱命名法(server-address)。由于URL是大小写敏感的，如果用驼峰命名在输入的时候就要求区分大小写，一个是增加输入难度，另外也容易输错，报404。
支付宝用的是蛇形命名法，stackoverflow.com和github.com用的是脊柱命名法：
（例如 https://help.github.com/articles/why-are-my-commits-linked-to-the-wrong-user/#commits-are-not-linked-to-any-user
和
(\https://stackoverflow.com/questions/5262224/how-are-reddit-and-hacker-news-ranking-algorithms-used）
1.URI命名原则
（1）URI请求采用小写字母，数字，部分特殊符号（非制表符）组成。
（2）URI请求中不采用大小写混合的驼峰命名方式，尽量采用全小写单词，如果需要连接多个单词，则采用连接符“-”连接单词（脊柱命名法）
2. 使用-来让URI可读性更好
3. 使用/来表示资源的层级关系：
曾经Web上的URI都是冰冷的数字或者无意义的字符串，但现在越来越多的网站使用_或-来分隔一些单词，让URI看上去更为人性化。
例如国内比较出名的开源中国社区，它上面的新闻地址就采用这种风格：
如http://www.oschina.net/news/38119/oschina-translate-reward-plan。（我们统一使用-）
4. 避免层级过深的URI(推荐两级)
在url中表达层级，用于 按实体关联关系进行对象导航 ，一般根据id导航。
过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4 ，尽量使用查询参数代替路径中的实体导航，如 GET/animals?zoo=1&area=3 ；
5. 使用?用来过滤资源
6. 可以用来表示同级资源的关系
五．API规范：
多条件查询：
1.GET /api/版本号/资源s?过滤条件
例如：GET /api/v1/req-infos?过滤条件
http://localhost:8801/api/v1/req-infos?pageNumber=0&pageSize=10&state=2
分页多条件查询需求信息
单数据查询：
2.GET /api/版本号/资源s/id
例如：GET /api/v1/req-infos/1
http://localhost:8801/api/v1/req-infos/1
获取id为1的需求信息
分组多条件查询：
3.GET /api/版本号/资源s/group/groupColumn1,groupColumn2?过滤条件
例如：GET api/v1/req-infos/group/state?过滤条件
http://localhost:8801/api/v1/req-infos/group/state?source=2
获取根据state分组且source=2的需求列表信息的分组信息
例如：GET api/v1/req-infos/group/state,source?过滤条件
http://localhost:8801/api/v1/req-infos/group/state,source?source=2
获取根据state和source分组且source=2的需求列表信息的分组信息
资源保存：
4.POST /api/版本号/资源s
例如：POST /api/v1/req-infos
http://localhost:8801/api/v1/req-infos
新建一条需求信息
单数据更新：
6.PUT /api/版本号/资源s/ID
例如：PUT /api/v1/req-infos/1
http://localhost:8801/api/v1/req-infos/1
更新id为1的需求信息
根据主键批量更新：
7. PUT /api/v1/req-infos/batch/id1,id2,id3
例如：PUT /api/v1/req-infos/batch/id1,id2,id3
http://localhost:8801/api/v1/req-infos?batch=1,2,3
更新id为1,2,3的需求信息
根据除主键外其他字段批量更新：
8. PUT /api/v1/req-infos/batch?过滤条件
例如：PUT /api/v1/req-infos/batch?createDate=2018-04-20
http://localhost:8801/api/v1/req-infos?createDate=2018-04-20
更新createDate为2018-04-20的需求信息
单数据删除：
9.DELETE /api/版本号/资源s/ID
例如：DELETE /api/v1/req-infos/1
http://localhost:8801/api/v1/req-infos/1
删除id为1的需求信息
根据主键批量删除：
10. DELETE /api/v1/req-infos/batch/id1,id2,id3
例如：DELETE /api/v1/req-infos/batch/id1,id2,id3
http://localhost:8801/api/v1/reqInfos?batch=1,2,3
删除id为1,2,3的需求信息
根据除主键外其他字段批量删除：
11. DELETE /api/v1/reqInfos/batch?过滤条件
例如：DELETE /api/v1/reqInfos/batch?createDate=2018-04-20
http://localhost:8801/api/v1/reqInfos?createDate=2018-04-20
更新createDate为2018-04-20的需求信息
操作类：
运行一条流水线：
http://localhost:8801/api/v1/pipelines/{id}/runs
终止一条流水线：
http://localhost:8801/api/v1/pipelines/{id}/ends
校验流水线名称：
http://localhost:8801/api/v1/pipelines/validations
下载多个图片：
http://localhost:8801/api/v1/pictures/downloads
下载一个资源：
http://localhost:8801/api/v1/resources/{id}/downloads
六．过滤信息：
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
下面是一些常见的参数:
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?pageNumber=2&pageSize=100：指定第几页，以及每页的记录数。
?orderBy=name&sort=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?reqTitle=新业务：指定筛选条件
七．状态码：
对于添加（POST）、修改（PUT）这类方法我们需要返回添加或更新后的数据以备前端使用（注意：对前端不关心的数据可以不做返回）
（一般GET请求成功返回200加对象、集合，
POST/PUT请求成功返回201加对象、集合，
DELETE求成功返回204，对于失败的请求代码中暂时不去处理）
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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
原文链接：https://blog.csdn.net/qq_38658642/article/details/101016741
