Niffler

8.2 REST API设计规范

Posted By 15352103

协议

使用https协议。

URL

  • 在RESTful架构中，每个路径代表一种资源，所以路径中不能有动词，只能有名词。所用名词尽量参考数据库表的设计。
  • URL路径名词均为复数。为了保证URL格式的一致性，建议使用复数形式。
  • 应该使用连字符”-“来提高URL的可读性，而不是使用下划线”_“。
  • URL路径中首选小写字母。
  • 将版本信息放入URL中。

    http请求方式

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

    过滤信息

    在获取资源的时候，有可能需要获取某些“过滤”后的资源，例如指定前10行数据： http://api.user.com/schools/grades/classes/boys?page=1&page-size=10

    数据格式

    使用json数据格式进行数据传递。

    状态码

    RESTful架构应该遵循统一接口原则，统一接口包含了一组受限的预定义的操作，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。
    如果按照HTTP方法的语义来暴露资源，那么接口将会拥有安全性和幂等性的特性，例如GET和HEAD请求都是安全的，无论请求多少次，都不会改变服务器状态。而GET、HEAD、PUT和DELETE请求都是幂等的，无论对资源操作多少次，结果总是一样的，后面的请求并不会产生比第一次更多的影响。
    下面列出了GET，DELETE，PUT和POST的典型用法：

    GET

  • 安全且幂等
  • 200（OK） 表示已在响应中发出
  • 204（无内容） 资源为空
  • 301（Moved Permanently） 资源的URL已被更新
  • 303（See Other） 其他（如，负载均衡）
  • 304（not modified）资源未更改（缓存）
  • 400 （bad request）指代坏请求
  • 404 （not found）资源不存在
  • 406 （not acceptable）服务端不支持所需表示
  • 500 （internal server error）通用错误响应
  • 503 （Service Unavailable）服务端当前无法处理请求

    POST

  • 不安全且不幂等
  • 200（OK）如果现有资源已被更改
  • 201（created）如果新资源被创建
  • 202（accepted）已接受处理请求但尚未完成（异步处理）
  • 301（Moved Permanently）资源的URL被更新
  • 303（See Other）其他（如，负载均衡）
  • 400（bad request）指代坏请求
  • 404 （not found）资源不存在
  • 406 （not acceptable）服务端不支持所需表示
  • 409 （conflict）通用冲突
  • 412 （Precondition Failed）前置条件失败（如执行条件更新时的冲突）
  • 415 （unsupported media type）接受到的表示不受支持
  • 500 （internal server error）通用错误响应
  • 503 （Service Unavailable）服务端当前无法处理请求

    PUT

  • 不安全但幂等
  • 200 （OK）如果现有资源已被更改
  • 201 （created）如果新资源被创建
  • 301（Moved Permanently）资源的URL已更改
  • 303 （See Other）其他（如，负载均衡）
  • 400 （bad request）指代坏请求
  • 404 （not found）资源不存在
  • 406 （not acceptable）服务端不支持所需表示
  • 409 （conflict）通用冲突
  • 412 （Precondition Failed）前置条件失败（如执行条件更新时的冲突）
  • 415 （unsupported media type）接受到的表示不受支持
  • 500 （internal server error）通用错误响应
  • 503 （Service Unavailable）服务端当前无法处理请求

    DELETE

  • 不安全但幂等
  • 200 （OK）资源已被删除
  • 301 （Moved Permanently）资源的URIL已更改
  • 303 （See Other）其他（如，负载均衡）
  • 400 （bad request）指代坏请求
  • 404 （not found）资源不存在
  • 409 （conflict）通用冲突
  • 500 （internal server error）通用错误响应
  • 503 （Service Unavailable）服务端当前无法处理请求