RESTful接口设计-路径设计

RESTful风格接口设计思考点

1.>请求路径---以当前接口操作的资源，一个使用资源复数作为路径，比如：/employees

简而言之 就是 RESTful接口设计-路径一般就是操作实体对象复数。

2.>请求方式---根据接口对资源操作决定 增：POST 删：DELETE 改：PUT 查：GET

RESTful方式：

http://www.langfeiyes.cn/enployees

新增：POST

更新：PUT

删除：DELETE

查询：GET

EG:

GET/zoos：列出所有 动物园

POST/zoos：新建一个动物园

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

PUT/zoos{id}：更新某个指定动物园的信息（提供该动物园的全部信息）

PATCH/zoos{id}：更新某个指定动物园的信息（提供该动物园的部分信息）

DELETE/zoos{id}：删除某个动物园

GET/zoos{id}/animals：列出某个动物园的所有动物

对比：

获取某个部门的所有员工

GET/employee/getByDeptId 以前的 比较随意

GET/departmens/{id}/employees restful风格

3.>请求参数

没有固定，根据接口的功能而定，可以说是由需求决定

4.>请求响应

RESTful对响应值，做出了细致的约定：

GET /collection：返回资源对象的列表（数组）

GET /collection/resource：返回单个资源对象

POST/collection：返回新生成的资源对象

PUT/collection/resource：返回完整的资源对象

PATCH/collection/resource：返回完整的资源对象

DELETE/collection/resource：返回一个空文档

以上数据都返回JSON格式

真实开发中，具体响应什么数据，以公司规定/操作需求需要为主。

HTTP 响应状态码

200 OK-[GET]:服务器成功返回用户请求的数据。
201CREATED-[POST/PUT/PATCH]:用户新建或修改数据成功。

202 Accepted-U:表示一个请求已经进入后台排队(异步任务)

204 NO CONTENT-DELETE]:用户的除数现成功
400 INVALID REQUEST-IPOST/PUT/PATCH]:用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该模作是幕等的

401 Unauthorized-:表示用户没有权限(令牌 用户名、密码错误)。
403 Forbidden-U表示用户得到授权(与401错误相对)，但是访可是被禁止。
404 NOT FOUND-:用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幕等的。

406 Not Acceptable-[GET]:用户请求的格式不可得(比如用户请求jSON格式，但是只有XML格式)。

410 Gone-[GET]用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity[POST/PUT/PATCH]当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR*1:服务题发生错湿，用户将无法判新发出的请求是否成功。

资源的表现形式

文本可以用TXT表现，也可以用HTML表现，也可以用XML表现，同样可以用JSON表现，甚至科研采用二进制进行表现。

图片可以用JPG表现，PNG格式进行表现，也可以用TIFF格式进行表现。

而他的具体表现形式，应该在HTTP请求的头信息中用

Accept和Content-Type字段指定，这两个字段才是对“表现”的描述。

accept:application/json

content-type:application/json

Accept与Content-Type的区别

1.Accept属于请求头，Content-Type属于实体头。

Http报头分为通用报头，请求报头，响应报头和实体报头

请求方的http报头结构：通用报头|请求报头|实体报头

响应方http报头结构：通用报头|响应报头|实体报头

2.Accept代表发送数据（客户端）希望接受到的数据类型。

Accept：application/json;

代表客户端希望接受的数据类型是json类型，后台返回json数据

Content-Type代表数据（客户端|服务器）发送的实体数据类型。

Content-Type：application/json

代表发送端发送的数据格式是json，后台就要以这样的格式来接受发送过来的数据。