RESTful API 设计

之前有过多次面试别人的经历，大多简历上会写上使用 RESTful API 进行设计或者对其熟悉。然而问下来，却一知半解。

如果有读者不了解 RESTful API，可以先看看这篇。

问题

请你设计一下用户登录登出的 API。

大多数面试者给出的回答是：

使用 POST 方法，登录的 URL 为 /api/v1/login，登出为 /api/v1/logout。其中登录的请求会带上 JSON 格式的用户名与密码。

不是 URL 上带有 /api/v1 或者使用了 JSON ，就是 RESTful API。这个回答包含几个常见的错误：

1. URL 中使用动词，而非名词，比如 login，logout。
2. HTTP 方法使用不对，POST 一般用于服务器资源的创建。

整体暴露出面试者缺乏对 RESTful API 设计的深入理解。

解决

RESTful API 的核心在于将对服务器资源的操作，封装在 HTTP 原语之中。包括以下两点：

1. URL 代表服务器上的某种资源，所以 URL 必须是名词形式的。
2. 使用 HTTP 方法来操作服务器资源，代表了资源的增删改查，比如：
   • GET，获取某个资源；
   • POST，创建一个资源；
   • PUT，更新整个资源；
   • PATCH，更新某个资源的一部分；
   • DELETE，删除某个资源。

所以针对用户登录登出的 API 设计，首先需要思考我们操作的服务器资源是什么？ 其中一个答案是 session，用户登录时，我们会创建（POST）一个 session 来标识用户在线；登出时，删除（DELETE）这个 session，表示用户已经下线。

我认为较好的回答是这样的：

登录登出的 URL 都为 /api/v1/sessions，登录使用 POST 方法，登出使用 DELETE 方法。其中登录的请求会带上 JSON 格式的用户名与密码。