RESTful API 规范

Posted 2021-02-02

首先 RESTful 是一种软件架构风格或者说是一种设计风格，并不是标准，它只是提供了一组设计原则和约束条件，主要用于客户端和服务器交互类的软件。

一、协议

　　在 url 接口中推荐使用 Https 协议，让网络接口更加安全。（简单讲是 Http 的安全版。即 Http 下加入SSL层，Https 的安全基础是 SSL，因此加密的详细内容就需要SSL）

二、接口

　　在 url 中可以体现这是个 API 接口。

https://127.0.0.1:8000/api/

三、版本

　　在 url 中可以体现版本号。

https://127.0.0.1:8000/api/v1/

四、路径

　　在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以 API 中的名词也应该使用复数。

<!-- 多条数据 -->
http://127.0.0.1:8000/api/v1/courses/
<!-- 单条数据 -->
http://127.0.0.1:8000/api/v1/course/1/

五、筛选

　　如果数据数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。

?page=2

六、状态码

　　服务器应向用户返回状态码和提示信息。

七、错误处理

　　如果发生错误，就应该向用户返回出错信息。

{"code": 1000, "error": "用户名或密码错误！"}

八、请求方式

　　可以根据 Http 不同的请求 method，进行不同的资源操作。（GET、POST、PUT、PATCH、DELETE）

九、Hypermedia API

　　RESTful API 最好做到 Hypermedia，即返回结果中提供链接，连向其他 API 方法。

十、其他

　　服务器返回的数据格式，应该尽量使用JSON，避免使用XML。