RESTful API 规范

首先 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。

原文地址:https://www.cnblogs.com/believepd/p/10256319.html