Restful API规范

Restful API规范：

1：协议

Restful API与用户的通信协议，总是使用http协议。

 

2:

域名

应该尽量将api部署在专用域名之下。

https://api.example.com

如果确定api很简单，不会有进一步的扩展，可以考虑放在主域名下

https://example.com/api/

3:

版本

应该将api的版本号放入url中

https://api.example.com/version/

另一种做法将版本号放入http头信息中，但不如放入url方便直观

 

4：路径

路径又称为“终点”（endpoint），表示api的具体网址

在restful架构中，每个网址代表一种资源（resource），所以网址中不能有

动词，只能有名词，而且所用的名词往往和数据库的表名对应。一般来说，数据库

中的表都是同种记录的集合，所以api中的名词也应该使用复数。

 

如动物园的api接口定义为：

 

https://api.example.com/v1/zoos

https://api.example.com/v1/animals

https://api.example.com/v1/employees

 

5:http动词

 

post (create): 在服务器中新建一个资源

delete (delete) ：从服务器删除资源

put (update)：在服务器更新资源（客户端提供改变后的完整资源）

get (select)：从服务器取出资源（一项或者多项）

 

6：过滤信息

如果记录数量很多，服务器不能将它们都返回用户，

api应该提供参数，过滤返回结果

？page=1；

 

7：状态码

服务器向用户返回的状态码和提示信息，常见的有：

200 ok

201 created

202 accepted 表示请求已经进入后台排队（异步任务）

204 no content [delete]: 用户删除数据成功

400 ：无效请求，请求出错，服务器没有新建或修改操作

401： 未授权，权限错误

403 ：forbidden，用户得到授权，但是访问禁止

404：资源不存在，服务器没有进行操作，该操作是幂等的

406：no acceptable ：用户请求的格式不可得（如用户请求格式（json，xml）不存在）

410：gone：用户资源永久删除，且不会在得到

422：unprocessable entity [post/put/patch] 当创建一个对象时，

发生一个验证错误。

500：INTERNAL SERVER ERROR -[*] : 服务器发生错误，

用户将无法判断请求是否成功。

 

8：错误处理

如果产生错误，就应该向用户返回错误信息，一般来说，返回的信息中，

将error作为键名。出错信息作为键值即可

{

error:"Invalid API key"

}

 

9:返回结果

针对不同操作，服务器向用户返回的结果应该符合以下的规范。

GET /collection： 返回资源对象的列表

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

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

PUT：/collection/resource: 返回完整的资源列表

PATCH /collection/resource: 返回完成的资源对象

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