服务端 API 接口设计最佳实践

在移动互联网开发领域，我们经常需要针对移动设备，提供数据访问接口。在移动时代以前，接口设计并没有面对这么大的挑战，因为那时期的应用开发，前后端的区分并没有那么明显，需要专门设计接口的场景并不是很多。

然而，进入移动互联网时代，几乎所有的App数据访问，都是走的接口形式。而且，针对已经发布了安卓、iOS客户端版本的接口的重大修改，变得几乎不可能。于是，预先设计正确的、良好的接口，就显得格外重要。

让我们来看看如今，在业内被广泛采用的接口设计最佳原则。

API设计核心原则

• 它应该遵循Web标准
• 它应该对开发者友好
• 它在使用上应该保持简单、直观和一致性，不仅仅是容易使用，而应该让使用者感到愉悦
• 它应该是有效率的

采用RESTful URLs 和 actions
如果说有一个实践，在世界范围内被广泛采用，那就是RESTful原则。RESTful这个原则是由Roy Fielding在他的学术论文network based software architectures的第五章里被第一次提到。

REST的核心思想是，把API按照逻辑上的资源来进行区分。这些资源被HTTP的不同方法( GET, POST, PUT, PATCH, DELETE )进行请求，每个方法代表不同的含义。

举个例子，如果我有一个对用户进行操作的接口。那么，针对这个用户的CRUD操作，采用RESTful的设计风格就是这个样子的，

GET /users - 获取用户列表
GET /users/12 - 获取ID等于12的用户
POST /users - 创建一个新用户
PUT /users/12 - 更新ID等于12的用户
PATCH /users/12 - 部分更新ID等于12的用户
DELETE /users/12 - 删除ID等于12的用户

REST的伟大之处在于，采用了既有的HTTP methods，在一个单独的/users链接下，实现了多样的功能操作。你不需要遵循任何的命名规范，仅仅需要一个干净和整洁的URL结构 /users。

总是使用HTTPS

总是使用HTTPS，没有例外。当今，只要连接了互联网，你的API就能够在世界任何地方被访问。不是所有的访问都是安全的。有一些API数据没有被加密，很容易遭到劫持并被篡改。

撰写接口文档

好的文档，和好的接口同样重要。接口文档需要被很容易地找到和访问。大部分开发者会在进行接口开发之前，检查并查看接口文档。如果这些接口文档是写在PDF文档里，或者需要登录才能查看，那将不仅仅是难于查找，还不利于搜索。

接口文档应该描述完整的 Request/Response Cycle，并附上具体的例子。最好是，这些例子应该是真实可以访问的，比如把链接复制到浏览器里执行，或者用curl执行。GitHub 和 Stripe 的接口文档都写得很不错。

一旦你发布了一个API，那意味着，在没有通知调用者的情况下，你有责任不去破坏该接口的已有功能。如果你在今后修改该接口，需要及时更新接口文档，并且在发布接口的更新之前，及时通知你的接口调用者。

Versioning
总是给你的API加上版本化。API版本化能够让你的API迭代地更快，防止老的请求访问你的API最新版。这样能够让你在进行API重大升级时，能够持续对老版本API进行一段时间的支持。

有很多的人在讨论，API的版本化，应该体现在URL上，还是在请求Header里。理论上讲，应该放在Header里。

API被发布出来，不会永远不变。变化是不可避免的。重要的是，我们怎么去管理这种变化。

限制API返回的字段
API调用者有时候不希望资源的所有字段都返回。如果能够在调用时，选择API能够返回的字段，将减少网络传输流量，加速调用方的业务处理。

可以使用 fields 查询参数来限制API返回的字段。比如，以下请求只返回需要的字段信息：
GET /users/12?fields=id,user_name,age


错误代码
就像HTML页面出错了展示的错误消息一样，API在出错时也应该提供一个有用的错误消息给调用方。

API应该总是返回合理的HTTP状态码。API的错误通常分为两类：客户端调用错误使用的400系列状态码，和服务端处理错误使用的500系列状态码。

一个JSON错误消息应该包含这么几个部分，一个有用的错误消息，一个唯一的错误码( 方便在接口文档里查到更详细的错误描述 )和一个详尽的错误描述。就像这样：

{
  "code" : 1234,
  "message" : "Something bad happened :(",
  "description" : "More details about the error here"
}

对于数据校验错误，错误消息应该包含具体出错的字段信息，就像这样：

{
  "code" : 1024,
  "message" : "Validation Failed",
  "errors" : [
    {
      "code" : 5432,
      "field" : "first_name",
      "message" : "First name cannot have fancy characters"
    },
    {
       "code" : 5622,
       "field" : "password",
       "message" : "Password cannot be blank"
    }
  ]
}

HTTP状态码

HTTP定义了一系列有意义的状态码，API可以直接采用这些状态码进行返回。这能帮助API调用方更好地处理返回结果。常用的HTTP状态码有：

• 200 OK
• 201 Created
• 204 No Content
• 304 Not Modified
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 405 Method Not Allowed
• 410 Gone
• 415 Unsupported Media Type
• 422 Unprocessable Entity
• 429 Too Many Requests
• 500 Internal Server Error
• 503 Service Unavailable

总结

API就是开发者的”User Interface”。花一点精力，确保API不仅仅是满足功能，而是让使用者感到愉悦。

译自( 有删减 )：
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#limiting-fields
参考资料：
https://github.com/ZhangBohan/http-api-design-ZH_CN
http://www.toptal.com/api-developers/5-golden-rules-for-designing-a-great-web-api

                                                                        杏树林研发 刘龙军