如何搭建一个好的API

此文为本人的一篇阅读笔记，英文原文。

RESTful 基础框架

REST 意为"Representational State Transfer"，即“表现层状态转换”。它并非是创建一个 API 的唯一方式，但肯定是目前最流行的，以至于大部分非开发人员都对这个词不陌生。

RESTful 软件有留个关键特征：

1. CS 架构(Client-Server architecture)
2. Statelessness(无状态)
3. Cacheability(可缓存)
4. Layered system(分层系统)
5. Code on demand(按需代码) - optional
6. Uniform interface(齐整接口)

这些对于日常使用来说太理论化了。

从可操作性角度考虑，作者总结了一些原文里面的实用的部分。

HTTP 动词

这些 HTTP 动词(request)是为了增加目的性和意义。包含了我们熟悉的 PUT, DELETE, GET, POST.

回答“从这我能去往哪里？”问题

一个简单的例子：GET /api/book/12，获取 id 为 12 的书的信息

一个好的 API 应该有哪些特点？

错误异常处理

这是个很基础的东西，如果有任何的错误异常，我们需要第一时间就知道。

我们很熟悉的 HTTP 状态码：

1. 2xx 表示 OK
2. 3xx 表示“你寻找的资源在别处”
3. 4xx 表示客户端出了点差错(比如 404，客户端试图访问一个不存在的资源)
4. 5xx 表示服务器端除了问题

当我们设计 API 的时候要花点时间好好考虑采用哪个代码。

说明文档

好的文档对于任何源代码来讲都是必要的。API 代码也不例外。

有一个帮助文档自动更新的工具，叫做 Swagger，可以尝试下。还有一个替代产品叫做 Slate，可以搜搜看。

可缓存性 Cacheability

对于一些系统来讲这一条并不是必须的。

革命性 API 设计

开发现代 API 中最重要的部分是适应性。

APIs should not dictate the implementation

自行细品吧。

结束语：

这方面的知识还是需要多补充下。多写写后端代码之后再回来看可能会有更多的收获。