7点关于RESTful规范的API接口设计的想法

转：https://segmentfault.com/a/1190000004051246

 

在项目中，需要为APP撰写API。刚开始接触的时候，并没有考虑太多，就想提供URL，APP端通过该URL进行查询、创建、更新等操作即可。但 再对相关规范进行了解后，才发现，API的设计并没有那么简单，远远不是URL的问题，而是一个通信协议的整体架构。因此，我写这篇文章，用来记录自己的 一些心得，并不断完善。并提供关于RESTful API的一些参考文献。

1. 使用SSL（https）来提供URL

首先，使用https可以在数据包被抓取时多一层加密。我们现在的APP使用环境大部分都是在路由器WIFI环境下，一旦路由器被入侵，那么黑客可 以非常容易的抓取到用户通过路由器传输的数据，如果使用http未经加密，那么黑客可以很轻松的获取用户的信息，甚至是账户信息。

其次，即使使用https，也要在API数据传输设计时，正确的采用加密。例如直接将token信息放在URL中的做法，即使你使用了https，黑客抓不到你具体传输的数据，但是可以抓到你请求的URL啊！（查了资料了，https用GET方式请求，也仅能抓到域名字符部分，不能抓到请求的数据，但是URL可以在浏览器或特殊客户端工具中直接看到。多谢下面的朋友指正错误）因此，使用https进行请求时，要采用POST、PUT或者HEAD的方式传输必要的数据。

2. 使用GET、POST、PUT、DELETE这几种请求模式

请求模式也可以说是动作、数据传输方式，通常我们在web中的form有GET、POST两种，而在HTTP中，存在下发这几种。

GET (选择)：从服务器上获取一个具体的资源或者一个资源列表。
POST （创建）： 在服务器上创建一个新的资源。
PUT（更新）：以整体的方式更新服务器上的一个资源。
PATCH （更新）：只更新服务器上一个资源的一个属性。
DELETE（删除）：删除服务器上的一个资源。
HEAD ： 获取一个资源的元数据，如数据的哈希值或最后的更新时间。
OPTIONS：获取客户端能对资源做什么操作的信息。

3. 在URI中体现资源，而非动作

阅读RESTful架构的参考文献之后，你会了解什么是资源的概念，以及REST的确切含义。再构建API的URL的时候，URI中应该仅包含资源 （对象），而不要加入动作。比如 /user/1/update ，其中update就是一个动作，虽然我们希望通过这个URI来实现用户ID为1的用户进行信息更新，但是按照RESTful的规范，作为动作，应该用上 面的PUT来表示，所以请求更新用户信息，应该使用 PUT /user/1 来表示更新用户ID为1的用户信息。

如果去对应上面的请求模式，GET表示显示、列出、展示，POST表示提交、创建，PUT表示更新，DELETE表示删除。

<?php
    $ch = curl_init();
    $url = 'http://api.xxx.com/user';
    $data = "name=姓名&email=[e-mail]";
    // 添加参数
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    // 执行HTTP请求
    curl_setopt($ch , CURLOPT_URL , $url);
    $res = curl_exec($ch);

    var_dump(json_decode($res));
?>

上面这段代码中$url仅仅是提供到了user，而并没有提供add，服务端通过识别POST请求来确定，这是一个创建用户的操作。但是还有一些数据并没有用以处理数据，而是用以验证的，比如下文的鉴权，可以将这些信息通过header进行传输，下方详细展示。

4. 版本

API的开发直接关系了APP是否可以正常使用，如果原本运行正常的API，突然改动，那么之前使用这个API的APP可能无法正常运行。APP是 不可能强迫用户主动升级的，因此，通过API版本来解决这个问题。也就是说，API的多个版本是同时运行的，而且都要保证可以正常使用。

按照RESTful的规范，不同的版本也应该用相同的API URL，通过header信息来判断版本，再调用不同版本的程序进行处理。但是这明显会给开发带来巨大的成本。解决办法有两种：1.新版本兼容旧版本，所 有旧版本的动作、字段、操作，都在新版本中可以被实现，但明显这样的维护成本很大；2.不同的版本，用不同的URL来提供服务，比如再URL中通过v1、 v2来区分版本号，我则更喜欢采用子域名的方式，比如v2.api.xxx.com/user的方式。

5. HTTP响应码

在用户发出请求，服务端对请求进行响应时，给予正确的HTTP响应状态码，有利于让客户端正确区分遇到的情况。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

6. 返回值结构

在完成了上面的URL部署之后，接下来我们来看看返回结果应该怎么样来确定。我看到大部分文献中指出，最好使用JSON进行返回，而非xml。我认 为原因可能有两点：1. JSON可以很好的被很多程序支持，javascript的ajax可以直接将JSON转换为对象。2. JSON的格式在容量上比xml小很多，可以减低宽带占用，提高传输效率。

那么，返回值应该怎么去部署呢？

首先，字段的合理返回，数据的包裹。因为返回值中，我们常常要对数据进行区分分组，或者按照从属关系打包，所以，我们再返回时，最好有包裹的思想，把数据存放在不同的包裹中进行返回。

{
  'error_code' : 0,
  'data' : {
                   'user_id' : 1,
                   'username' : 'xiaomin'
              },
  'server_time': 14939939
}

上面返回的JSON中，使用data来作为数据包，将所有数据统一以这个字段进行包裹。除了data，也可以用list等其他形式的包裹，命名都是自己来根据自己的需要确定的。

{
  'error_code' : 0,
  'list' : [
              {'user_id':1,'username':'xiaoming'},
              {'user_id':2,'username':'goudan'}
            ]
  'server_time': 14939939
}

总之，不要不分包，直接把所有数据和一些你想返回的全局数据混在一起进行返回。

其次，错误码。错误码的作用是方便查找错误原因，通常情况下，我喜欢用error_code来表示，当error_code=0时，表示没有发生错 误，当error_code>0时，发生了错误，并且提供较为详细的文档，告诉客户端对应的error_code值所产生的错误的原因和位置。

最后，空白压缩和字符转换。也就是返回的JSON结果不要换行和空格，用一行返回结果，使整个结果文本容量最小。同时，中文等字符或结果中有引号，都进行字符转换，防止结果无法被正确识别。

7. 鉴权

其实也就是客户端的权限控制。一般而言，我会采用给客户端分发一个token来确定该客户端的唯一身份。客户端在请求时，通过这个token，判断发出请求的客户端所对应的用户，及其相关信息和权限。

前文已经提到了，token信息不是用来进行处理的数据，虽然可以通过POST、PUT等进行数据提交或传输，但是从RESTful规范来讲，它不属于操作数据，在服务端进行处理时，仅是利用token进行鉴权处理，所以，我的建议是通过header来发送token。

<?php
    $ch = curl_init();
    $url = 'http://api.xx.com/user';
    $header = array(
        'token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'X-HTTP-Method-Override: PUT'        
    );
    $data = array(
         'user_name' => 'xiaoming',
         'user_email' => '[e-mail]'
    );
    // 添加apikey到header
    curl_setopt($ch, CURLOPT_HTTPHEADER  , $header);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    // 执行HTTP请求
    curl_setopt($ch , CURLOPT_URL , $url);
    $res = curl_exec($ch);

    var_dump(json_decode($res));
?>

上面的代码中，通过将CURLOPT_CUSTOMREQUEST设置为PUT，就可以发出PUT请求，发出的PUT请求，仍然需要通过 CURLOPT_POSTFIELDS来传输数据。服务端接受PUT请求时，首先要对发出请求的客户端进行token验证，通过对token的处理，查找 到拥有该token的实际用户，从而确定了将对哪一个用户进行信息更新操作。

国内大部分API对PUT、DELETE请求进行了阉割，更不用提HEAD、PACTH、OPTIONS请求。实际上，国内大部分开放API仅支持 GET和POST两种，部分API支持将app key信息通过header进行发送。在面对这种情况下，我们不得不抛弃标准的RESTful规范，在url中加入get、add、update、 delete等动作词汇，以补充由于请求支持不完善带来的动作区分问题。如果仅支持GET和POST，那么所有需要保密的数据，绝对不可以用GET来进行 请求，而必须用POST。

参考文献

《理解RESTful架构》《RESTful API 设计指南》
《好RESTful API的设计原则》
《我所理解的RESTful Web API [设计篇]》
《https工作原理》