RESTful API 设计规范

RESTful API 设计规范

协议

所有API前后端通信都使用HTTPS协议。

API 根地址

API的根地址应该保持简单,如:

- api.engineer.com/*
- www.engineer.com/api/*

如果应用很庞大或者预计后期会变的很庞大,应该将api放到子域下(api.engineer.com)。这样可以保持规模化上的灵活性。

版本

所有的API必须前后兼容。必须在引入新版本API的同时确保旧版本API仍然可用。所以要为API提供版本支持。如如下两种方式:

  • 在URL中嵌入版本号
api.engineer.com/v1/*

这种做法版本号比较直观,还有一种嵌入版本号是放在HTTP Header头中

  • 通过媒体类型来指定版本信息
Accept: application/vnd.engineer.com.v1+json

其中 vnd 表示 Standards Tree 标准树类型,有三个不同的树: xprsvnd。你使用的标准树需要取决于你开发的项目

  • 未注册的树(x)主要表示本地和私有环境
  • 私有树(prs)主要表示没有商业发布的项目
  • 供应商树(vnd)主要表示公开发布的项目

端点

端点就是指定特定资源的URL。端点设计必须遵守以下原则:

  • URL的命名必须全部小写
  • URL中资源的全名必须是名词,并且必须是复数形式
  • 必须优先使用Restful类型的URL
  • URL必须是易读的
  • URL一定不可暴露服务器架构

至于 URL 是否必须使用连字符(-) 或下划线(_),不做硬性规定,但要根据团队情况统一一种风格。

HTTP动词

对于资源的具体操作类型,由 HTTP 动词表示。常用的 HTTP 动词有下面五个

  • GET:从服务器取出资源(一项或多项)。
  • POST:在服务器新建一个资源。
  • PUT:在服务器更新资源(客户端提供改变后的完整资源)。
  • PATCH:在服务器更新资源(客户端提供改变的属性)。
  • DELETE:从服务器删除资源。

注意:

1 删除资源 必须 用 DELETE 方法 
2 创建新的资源 必须 使用 POST 方法 
3 更新资源 应该 使用 PUT 方法 
4 获取资源信息 必须 使用 GET 方法

响应

所有的 API 响应,必须遵守HTTP设计规范,必须选择合适的 HTTP 状态码。一定不可所有接口都返回状态码为200的HTTP响应。

以上内容摘录自:https://github.com/godruoyi/restful-api-specification