Restful风格接口规范学习笔记

REST是设计风格而不是标准。REST通常基于使用HTTP，URI，和XML，JSON以及HTML这些现有的广泛流行的协议和标准。

标准：

1. 资源是由URI来指定。
2. 对资源的操作包括获取、创建、修改和删除资源，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。
3. 通过操作资源的表现形式来操作资源。
4. 资源的表现形式则是XML，JSON或者HTML，当然也可以是任何其他的格式。
5. 在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的“集合"（collection），所以API中的名词也应该使用复数。

设计原则：

1. 每一个URI代表一种资源;
2. 同一种资源有多种表现形式(xml/json等)，它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现"的描述，如：accept:application/json，content-type:application/json;
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。

URL及参数设计规范 :

1. URL末尾不需要出现斜杠/;
2. 在URL中使用斜杠/是表达层级关系的;
3. 在URL中可以使用连接符-, 来提升可读性。比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可读性更好;
4. 在URL中不允许出现下划线字符_;
5. 在URL中尽量使用小写字符;
6. 在URL中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的;
7. 在URL中使用复数形式。

错误示例：

状态码不恰当使用方式，即使发生错误，也返回200状态码，把错误信息放在返回的数据体内，如下所示：

HTTP/1.1 200 OK

Content-Type:application/json

{

      "status":"failure",

      "data":{

            "error":"there some error ."

      }

}

上述方式，在页面解析数据体之后，才能得知操作失败，该做法实际是取消了状态码。

正确方式是，状态码反应发生错误，具体的错误信息放在数据体返回：

HTTP/1.1 400 Bad Request

Content-Type:application/json

{

      "error":"Invalid payload.",

      "detail":{

            "username":"this field is required."

      }

}

状态码说明

状态码	含义
200 OK - [GET]	服务器成功返回用户请求的数据
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 - [*]	用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的
405 Method Not Allowed	方法不允许，服务器没有该方法
406 Not Acceptable - [GET]	用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）
410 Gone -[GET]	用户请求的资源被永久删除，且不会再得到的
422 Unprocesable entity - [POST/PUT/PATCH]	当创建一个对象时，发生一个验证错误
500 INTERNAL SERVER ERROR - [*]	服务器发生错误，用户将无法判断发出的请求是否成功