notes

服务端 RESTful API 规范

HTTP 请求类型

请求类型	状态描述
GET	成功的 GET 方法通常返回 HTTP 状态代码 200（正常）。 如果找不到资源，该方法应返回 404（未找到）。
POST	如果 POST 方法创建了新资源，则会返回 HTTP 状态代码 201（已创建）。如果该方法执行了一些处理但未创建新资源，则可以返回 HTTP 状态代码 200，并在响应正文中包含操作结果。如果客户端将无效数据放入请求，服务器应返回 HTTP 状态代码 400（错误的请求）。
PUT	与 POST 方法一样，如果 PUT 方法创建了新资源，则会返回 HTTP 状态代码 201（已创建）。 如果该方法更新了现有资源，则会返回 200（正常）或 204（无内容）。
DELETE	如果删除操作成功，Web 服务器应以 HTTP 状态代码 204 做出响应，指示已成功处理该过程，但响应正文不包含其他信息。 如果资源不存在，Web 服务器可以返回 HTTP 404（未找到）
HEAD	返回资源的元数据，支持 GET 方法的资源应该也支持 HEAD
PATCH	对资源进行部分更新
OPTIONS	获取有关请求的信息

标准请求头

这些请求头不是必须的，但如果用到，必须使用一致。

请求头	类型	描述
Authorization	String	授权验证
Date	Date	请求时间戳，但服务器不应该信任客户端时间
Accept	Content type	请求内容识别
Accept-Encoding	Gzip, deflate	内容的编码方式
Accept-Language	“en”, “es”, etc.	如果服务端支持本地化，则客户端需要设置此值
Accept-Charset	“UTF-8”, etc.	字符集
Content-Type	Content type	内容类型

标准响应头

响应头	Required	描述
Date	All responses	服务端处理请求的时间，基于格林威治时间，例：Wed, 24 Aug 2016 18:41:30 GMT
Content-Type	String	内容类型
Content-Encoding	String	编码方式

HTTP 状态码

状态码	状态名	状态描述
200	OK	请求成功
201	Created	已创建。成功请求并创建了新的资源
202	Accepted	已经接受请求，但未处理完成（异步任务）
204	No Content	服务器成功处理，但未返回内容
301	Moved Permanently	请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替
302	Found	与301类似。但资源只是临时被移动，客户端应继续使用原有URI
303	See Other	查看其它地址
400	Bad Request	客户端请求参数错误
401	Unauthorized	需要身份认证
403	Forbidden	拒绝执行此请求
404	Not Found	资源不存在
405	Method Not Allowed	请求方法被禁止
500	Internal Server Error	服务器内部错误
502	Bad Gateway	网关超时

API 命名规范

• 资源 URI 应基于名词（资源）而不是动词（对资源执行的操作）

  # 通过 POST 来创建订单
  https://adventure-works.com/orders // Good
  https://adventure-works.com/create-order // Bad
  

• 使用复数表示集合

  # 向集合 URI 发送 GET 请求可获取集合列表
  https://adventure-works.com/orders
  

• 在 URL 中做版本管理

  https://adventure-works.com/v1/activities/618/staffStates
  

• 统一使用 lowerCamelCase 命名规则。

异步操作

有时，POST、PUT、PATCH 或 DELETE 操作可能需要处理操作需要一段时间才能完成。 如果需要等待该操作完成后才能向客户端发送响应，可能会造成不可接受的延迟。在这种情况下，请考虑将该操作设置为异步操作。返回 HTTP 状态代码 202（已接受），指示该请求已接受进行处理。前端通过轮询来查询状态。

响应格式 & 示例

服务端应该以 application/json 作为默认格式。属性名遵循 lowerCamelCase。

正常情况的响应

正常响应的返回格式按照每个接口需要的格式来。

分页

常用的分页字段采用 page、size、sort_by、pagination。

在分页查询中，响应会返回 pagination 和 data 字段，例：

{
  data: [
    ...
  ],
  pagination: {
    page: 1,
    size: 10,
    count: 23
  }
}

错误情况的响应

发生错误的时候，服务端会根据错误的类型设置不同的 http 状态码，而且会返回一个 json 对象，里面包含 code、message 等字段。

error 对象可能包含的字段：

字段名	类型	Required	描述
code	String	必须	服务端定义的错误码
message	String	必须	人类可读的错误信息
target	String	不必须	导致错误发生的字段（属性名）
details	Array	不必须	是一个数组，表示请求期间发生的错误，内部包含 code 和 message 字段
innererror	String	不必须	这是一个嵌套的对象，每个嵌套的 innererror 对象都比其父对象表示更高级别的详细信息

例子：

// 例一
HTTP Status Code：400
{
  "code": "BadArgument",
  "message": "Previous passwords may not be reused",
  "target": "password",
  "innererror": {
    "code": "PasswordError",
    "innererror": {
      "code": "PasswordDoesNotMeetPolicy",
      "minLength": "6",
      "maxLength": "64",
      "characterTypes": ["lowerCase","upperCase","number","symbol"],
      "minDistinctCharacterTypes": "2",
      "innererror": {
        "code": "PasswordReuseNotAllowed"
      }
    }
  }
}

// 例二
HTTP Status Code：400
{
  "code": "BadArgument",
  "message": "Multiple errors in ContactInfo data",
  "target": "ContactInfo",
  "details": [
    {
      "code": "NullValue",
      "target": "PhoneNumber",
      "message": "Phone number must not be null"
    },
    {
      "code": "NullValue",
      "target": "LastName",
      "message": "Last name must not be null"
    },
    {
      "code": "MalformedValue",
      "target": "Address",
      "message": "Address is not valid"
    }
  ]
}