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=xxx@xxx.com";   // 添加参数   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响应状态码，有利于让客户端正确区分遇到的情况。

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' => 'xx@sfa.com'      );      // 添加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。

参考文献

我的个人博客 www.tangshuang.net 偶尔写一些学习中的感想和经验，希望有相同兴趣的朋友到博客来交流。