基于HTTPS的REST API设计初探-唐霜

在项目中，需要为APP撰写API。刚开始【访问 www.tangshuang.net 获取更多精彩内容】著作权归作者所有，禁止商业用途转载。接触的时候，并没有考虑太多，就想提供UR【本文受版权保护】【本文首发于唐霜的博客】L，APP端通过该URL进行查询、创建、【本文受版权保护】原创内容，盗版必究。更新等操作即可。但再对相关规范进行了解后未经授权，禁止复制转载。本文版权归作者所有，未经授权不得转载。，才发现，API的设计并没有那么简单，远本文作者：唐霜，转载请注明出处。【转载请注明来源】远不是URL的问题，而是一个通信协议的整【版权所有，侵权必究】【访问 www.tangshuang.net 获取更多精彩内容】体架构。因此，我写这篇文章，用来记录自己【关注微信公众号：wwwtangshuangnet】【本文受版权保护】的一些心得，并不断完善。并提供关于RES本文作者：唐霜，转载请注明出处。【访问 www.tangshuang.net 获取更多精彩内容】Tful API的一些参考文献。

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

首先，使用https可以在数据包被抓取时著作权归作者所有，禁止商业用途转载。【关注微信公众号：wwwtangshuangnet】多一层加密。我们现在的APP使用环境大部【原创不易，请尊重版权】【本文首发于唐霜的博客】分都是在路由器WIFI环境下，一旦路由器原创内容，盗版必究。未经授权，禁止复制转载。被入侵，那么黑客可以非常容易的抓取到用户本文版权归作者所有，未经授权不得转载。未经授权，禁止复制转载。通过路由器传输的数据，如果使用http未【版权所有】唐霜 www.tangshuang.net【原创不易，请尊重版权】经加密，那么黑客可以很轻松的获取用户的信著作权归作者所有，禁止商业用途转载。著作权归作者所有，禁止商业用途转载。息，甚至是账户信息。

【访问 www.tangshuang.net 获取更多精彩内容】未经授权，禁止复制转载。本文版权归作者所有，未经授权不得转载。原创内容，盗版必究。

其次，即使使用https，也要在API数【访问 www.tangshuang.net 获取更多精彩内容】【关注微信公众号：wwwtangshuangnet】据传输设计时，正确的采用加密。例如直接将未经授权，禁止复制转载。【原创内容，转载请注明出处】token信息放在URL中的做法，即使你本文版权归作者所有，未经授权不得转载。【版权所有】唐霜 www.tangshuang.net使用了https，黑客抓不到你具体传输的本文作者：唐霜，转载请注明出处。【关注微信公众号：wwwtangshuangnet】数据，但是可以抓到你请求的URL啊！因此本文版权归作者所有，未经授权不得转载。原创内容，盗版必究。，使用https进行请求时，要采用POS转载请注明出处：www.tangshuang.net【未经授权禁止转载】T、PUT或者HEAD的方式传输必要的数未经授权，禁止复制转载。原创内容，盗版必究。据。

著作权归作者所有，禁止商业用途转载。【关注微信公众号：wwwtangshuangnet】

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

请求模式也可以说是动作、数据传输方式，通【未经授权禁止转载】【作者：唐霜】常我们在web中的form有GET、PO原创内容，盗版必究。未经授权，禁止复制转载。ST两种，而在HTTP中，存在下发这几种【本文首发于唐霜的博客】本文版权归作者所有，未经授权不得转载。。

未经授权，禁止复制转载。【本文首发于唐霜的博客】

GET (选择)：从服务器上获取一个具体的资源【转载请注明来源】【版权所有】唐霜 www.tangshuang.net或者一个资源列表。

【未经授权禁止转载】

原创内容，盗版必究。

POST （创建）：在服务器上创建一个新的资源本文作者：唐霜，转载请注明出处。【版权所有】唐霜 www.tangshuang.net。

原创内容，盗版必究。

转载请注明出处：www.tangshuang.net

本文作者：唐霜，转载请注明出处。

PUT （更新）：以整体的方式更新服务器上的一【版权所有，侵权必究】【版权所有，侵权必究】个资源。

未经授权，禁止复制转载。

原创内容，盗版必究。

PATCH （更新）：只更新服务器上一个【版权所有】唐霜 www.tangshuang.net原创内容，盗版必究。资源的一个属性。

未经授权，禁止复制转载。

【原创内容，转载请注明出处】

转载请注明出处：www.tangshuang.net

著作权归作者所有，禁止商业用途转载。

DELETE （删除）：删除服务器上的一个资源。

【访问 www.tangshuang.net 获取更多精彩内容】

本文作者：唐霜，转载请注明出处。

HEAD ：获取一个资源的元数据，如数【作者：唐霜】【原创不易，请尊重版权】据的哈希值或最后的更新时间。

【作者：唐霜】

著作权归作者所有，禁止商业用途转载。

【转载请注明来源】

OPTIONS：获取客户端能对资源做什么【关注微信公众号：wwwtangshuangnet】【本文首发于唐霜的博客】操作的信息。

【原创内容，转载请注明出处】

本文作者：唐霜，转载请注明出处。

【转载请注明来源】

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

阅读RESTful架构的参考文献之后，你【版权所有】唐霜 www.tangshuang.net本文作者：唐霜，转载请注明出处。会了解什么是资源的概念，以及REST的确本文作者：唐霜，转载请注明出处。【本文受版权保护】切含义。再构建API的URL的时候，UR【访问 www.tangshuang.net 获取更多精彩内容】【关注微信公众号：wwwtangshuangnet】I中应该仅包含资源（对象），而不要加入动【版权所有，侵权必究】转载请注明出处：www.tangshuang.net作。比如 /user/1/update 本文作者：唐霜，转载请注明出处。【本文受版权保护】，其中update就是一个动作，虽然我们【本文受版权保护】【访问 www.tangshuang.net 获取更多精彩内容】希望通过这个URI来实现用户ID为1的用未经授权，禁止复制转载。【本文受版权保护】户进行信息更新，但是按照RESTful的未经授权，禁止复制转载。转载请注明出处：www.tangshuang.net规范，作为动作，应该用上面的PUT来表示原创内容，盗版必究。著作权归作者所有，禁止商业用途转载。，所以请求更新用户信息，应该使用 PUT【版权所有，侵权必究】本文作者：唐霜，转载请注明出处。 /user/1 来表示更新用户ID为1著作权归作者所有，禁止商业用途转载。本文版权归作者所有，未经授权不得转载。的用户信息。

本文作者：唐霜，转载请注明出处。【关注微信公众号：wwwtangshuangnet】著作权归作者所有，禁止商业用途转载。

如果去对应上面的请求模式，GET表示显示【本文受版权保护】【本文受版权保护】、列出、展示，POST表示提交、创建，P【本文首发于唐霜的博客】【本文受版权保护】UT表示更新，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仅仅是提供到了us转载请注明出处：www.tangshuang.net【版权所有】唐霜 www.tangshuang.neter，而并没有提供add，服务端通过识别【关注微信公众号：wwwtangshuangnet】本文作者：唐霜，转载请注明出处。POST请求来确定，这是一个创建用户的操本文作者：唐霜，转载请注明出处。本文版权归作者所有，未经授权不得转载。作。但是还有一些数据并没有用以处理数据，著作权归作者所有，禁止商业用途转载。本文作者：唐霜，转载请注明出处。而是用以验证的，比如下文的鉴权，可以将这未经授权，禁止复制转载。【作者：唐霜】些信息通过header进行传输，下方详细原创内容，盗版必究。【原创不易，请尊重版权】展示。

【未经授权禁止转载】本文版权归作者所有，未经授权不得转载。本文版权归作者所有，未经授权不得转载。【作者：唐霜】

4. 版本

API的开发直接关系了APP是否可以正常本文版权归作者所有，未经授权不得转载。【本文首发于唐霜的博客】使用，如果原本运行正常的API，突然改动本文版权归作者所有，未经授权不得转载。【版权所有，侵权必究】，那么之前使用这个API的APP可能无法【关注微信公众号：wwwtangshuangnet】转载请注明出处：www.tangshuang.net正常运行。APP是不可能强迫用户主动升级【转载请注明来源】本文作者：唐霜，转载请注明出处。的，因此，通过API版本来解决这个问题。【版权所有】唐霜 www.tangshuang.net【访问 www.tangshuang.net 获取更多精彩内容】也就是说，API的多个版本是同时运行的，原创内容，盗版必究。本文版权归作者所有，未经授权不得转载。而且都要保证可以正常使用。

按照RESTful的规范，不同的版本也应【未经授权禁止转载】未经授权，禁止复制转载。该用相同的API URL，通过heade【本文首发于唐霜的博客】著作权归作者所有，禁止商业用途转载。r信息来判断版本，再调用不同版本的程序进著作权归作者所有，禁止商业用途转载。未经授权，禁止复制转载。行处理。但是这明显会给开发带来巨大的成本本文作者：唐霜，转载请注明出处。著作权归作者所有，禁止商业用途转载。。解决办法有两种：1.新版本兼容旧版本，【原创内容，转载请注明出处】未经授权，禁止复制转载。所有旧版本的动作、字段、操作，都在新版本【原创内容，转载请注明出处】【关注微信公众号：wwwtangshuangnet】中可以被实现，但明显这样的维护成本很大；【本文受版权保护】本文作者：唐霜，转载请注明出处。2.不同的版本，用不同的URL来提供服务【原创内容，转载请注明出处】本文版权归作者所有，未经授权不得转载。，比如再URL中通过v1、v2来区分版本未经授权，禁止复制转载。本文作者：唐霜，转载请注明出处。号，我则更喜欢采用子域名的方式，比如v2【未经授权禁止转载】本文作者：唐霜，转载请注明出处。.api.xxx.com/user的方式【原创内容，转载请注明出处】【转载请注明来源】。

本文作者：唐霜，转载请注明出处。本文版权归作者所有，未经授权不得转载。【原创内容，转载请注明出处】

5. HTTP响应码

在用户发出请求，服务端对请求进行响应时，【关注微信公众号：wwwtangshuangnet】【本文首发于唐霜的博客】给予正确的HTTP响应状态码，有利于让客原创内容，盗版必究。【转载请注明来源】户端正确区分遇到的情况。

转载请注明出处：www.tangshuang.net原创内容，盗版必究。本文版权归作者所有，未经授权不得转载。

200 OK – [GET]转载请注明出处：www.tangshuang.net转载请注明出处：www.tangshuang.net：服务器成功返回用户请求的数据，该操作是著作权归作者所有，禁止商业用途转载。转载请注明出处：www.tangshuang.net幂等的（Idempotent）。

本文作者：唐霜，转载请注明出处。

转载请注明出处：www.tangshuang.net

【本文首发于唐霜的博客】

201 CREATED – 【关注微信公众号：wwwtangshuangnet】【原创内容，转载请注明出处】[POST/PUT/PATCH]：用户新【原创内容，转载请注明出处】【转载请注明来源】建或修改数据成功。

著作权归作者所有，禁止商业用途转载。

202 Accepted –本文作者：唐霜，转载请注明出处。转载请注明出处：www.tangshuang.net [*]：表示一个请求已经进入后台排队（著作权归作者所有，禁止商业用途转载。【版权所有，侵权必究】异步任务）

本文版权归作者所有，未经授权不得转载。

204 NO CONTENT ̵【未经授权禁止转载】【原创不易，请尊重版权】1; [DELETE]：用户删除数据成功未经授权，禁止复制转载。著作权归作者所有，禁止商业用途转载。。

【原创内容，转载请注明出处】

著作权归作者所有，禁止商业用途转载。

400 INVALID REQUEST 转载请注明出处：www.tangshuang.net著作权归作者所有，禁止商业用途转载。– [POST/PUT/PA著作权归作者所有，禁止商业用途转载。【作者：唐霜】TCH]：用户发出的请求有错误，服务器没【作者：唐霜】【本文受版权保护】有进行新建或修改数据的操作，该操作是幂等原创内容，盗版必究。【访问 www.tangshuang.net 获取更多精彩内容】的。

【关注微信公众号：wwwtangshuangnet】

【作者：唐霜】

401 Unauthorized 【原创不易，请尊重版权】【本文受版权保护】211; [*]：表示用户没有权限（令牌【未经授权禁止转载】【本文首发于唐霜的博客】、用户名、密码错误）。

【访问 www.tangshuang.net 获取更多精彩内容】

403 Forbidden –【原创内容，转载请注明出处】【转载请注明来源】; [*] 表示用户得到授权（与401错转载请注明出处：www.tangshuang.net【版权所有，侵权必究】误相对），但是访问是被禁止的。

本文版权归作者所有，未经授权不得转载。

原创内容，盗版必究。

【关注微信公众号：wwwtangshuangnet】

404 NOT FOUND –著作权归作者所有，禁止商业用途转载。著作权归作者所有，禁止商业用途转载。; [*]：用户发出的请求针对的是不存在本文作者：唐霜，转载请注明出处。【作者：唐霜】的记录，服务器没有进行操作，该操作是幂等【作者：唐霜】【版权所有】唐霜 www.tangshuang.net的。

著作权归作者所有，禁止商业用途转载。

【作者：唐霜】

406 Not Acceptable &【未经授权禁止转载】转载请注明出处：www.tangshuang.net#8211; [GET]：用户请求的格式未经授权，禁止复制转载。【版权所有】唐霜 www.tangshuang.net不可得（比如用户请求JSON格式，但是只【访问 www.tangshuang.net 获取更多精彩内容】【访问 www.tangshuang.net 获取更多精彩内容】有XML格式）。

原创内容，盗版必究。

【访问 www.tangshuang.net 获取更多精彩内容】

410 Gone -[GET]：用户请求原创内容，盗版必究。本文版权归作者所有，未经授权不得转载。的资源被永久删除，且不会再得到的。

未经授权，禁止复制转载。

【原创内容，转载请注明出处】

转载请注明出处：www.tangshuang.net

本文版权归作者所有，未经授权不得转载。

【关注微信公众号：wwwtangshuangnet】

原创内容，盗版必究。

著作权归作者所有，禁止商业用途转载。

6. 返回值结构

在完成了上面的URL部署之后，接下来我们【版权所有】唐霜 www.tangshuang.net著作权归作者所有，禁止商业用途转载。来看看返回结果应该怎么样来确定。我看到大本文作者：唐霜，转载请注明出处。【版权所有，侵权必究】部分文献中指出，最好使用JSON进行返回本文版权归作者所有，未经授权不得转载。转载请注明出处：www.tangshuang.net，而非xml。我认为原因可能有两点：1.【原创内容，转载请注明出处】【本文受版权保护】 JSON可以很好的被很多程序支持，ja【未经授权禁止转载】转载请注明出处：www.tangshuang.netvascript的ajax可以直接将JS【未经授权禁止转载】原创内容，盗版必究。ON转换为对象。2. JSON的格式在容【本文受版权保护】【关注微信公众号：wwwtangshuangnet】量上比xml小很多，可以减低宽带占用，提本文作者：唐霜，转载请注明出处。本文版权归作者所有，未经授权不得转载。高传输效率。

原创内容，盗版必究。【本文受版权保护】【未经授权禁止转载】

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

【关注微信公众号：wwwtangshuangnet】【本文首发于唐霜的博客】转载请注明出处：www.tangshuang.net【作者：唐霜】

原创内容，盗版必究。【原创内容，转载请注明出处】转载请注明出处：www.tangshuang.net著作权归作者所有，禁止商业用途转载。

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

上面返回的JSON中，使用data来作为【转载请注明来源】本文版权归作者所有，未经授权不得转载。数据包，将所有数据统一以这个字段进行包裹【作者：唐霜】【原创内容，转载请注明出处】。除了data，也可以用list等其他形本文版权归作者所有，未经授权不得转载。【转载请注明来源】式的包裹，命名都是自己来根据自己的需要确【访问 www.tangshuang.net 获取更多精彩内容】【版权所有】唐霜 www.tangshuang.net定的。

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

总之，不要不分包，直接把所有数据和一些你【转载请注明来源】本文版权归作者所有，未经授权不得转载。想返回的全局数据混在一起进行返回。

其次，错误码。错误码的作用是方便查找错误【关注微信公众号：wwwtangshuangnet】【作者：唐霜】原因，通常情况下，我喜欢用error_c原创内容，盗版必究。【作者：唐霜】ode来表示，当error_code=0原创内容，盗版必究。【未经授权禁止转载】时，表示没有发生错误，当error_co转载请注明出处：www.tangshuang.net【原创不易，请尊重版权】de>0时，发生了错误，并且提供较【原创不易，请尊重版权】原创内容，盗版必究。为详细的文档，告诉客户端对应的error原创内容，盗版必究。【本文受版权保护】_code值所产生的错误的原因和位置。

最后，空白压缩和字符转换。也就是返回的J原创内容，盗版必究。【原创不易，请尊重版权】SON结果不要换行和空格，用一行返回结果【本文受版权保护】【关注微信公众号：wwwtangshuangnet】，使整个结果文本容量最小。同时，中文等字本文作者：唐霜，转载请注明出处。本文作者：唐霜，转载请注明出处。符或结果中有引号，都进行字符转换，防止结【作者：唐霜】【转载请注明来源】果无法被正确识别。

7. 鉴权

其实也就是客户端的权限控制。一般而言，我著作权归作者所有，禁止商业用途转载。本文版权归作者所有，未经授权不得转载。会采用给客户端分发一个token来确定该【版权所有】唐霜 www.tangshuang.net【转载请注明来源】客户端的唯一身份。客户端在请求时，通过这著作权归作者所有，禁止商业用途转载。【未经授权禁止转载】个token，判断发出请求的客户端所对应转载请注明出处：www.tangshuang.net本文版权归作者所有，未经授权不得转载。的用户，及其相关信息和权限。

前文已经提到了，token信息不是用来进著作权归作者所有，禁止商业用途转载。【未经授权禁止转载】行处理的数据，虽然可以通过POST、PU【未经授权禁止转载】【本文首发于唐霜的博客】T等进行数据提交或传输，但是从RESTf本文版权归作者所有，未经授权不得转载。【原创内容，转载请注明出处】ul规范来讲，它不属于操作数据，在服务端【作者：唐霜】【转载请注明来源】进行处理时，仅是利用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_CU【原创不易，请尊重版权】本文作者：唐霜，转载请注明出处。STOMREQUEST设置为PUT，就可著作权归作者所有，禁止商业用途转载。【版权所有，侵权必究】以发出PUT请求，发出的PUT请求，仍然【本文受版权保护】转载请注明出处：www.tangshuang.net需要通过CURLOPT_POSTFIEL【版权所有】唐霜 www.tangshuang.net【未经授权禁止转载】DS来传输数据。服务端接受PUT请求时，【转载请注明来源】【关注微信公众号：wwwtangshuangnet】首先要对发出请求的客户端进行token验未经授权，禁止复制转载。本文版权归作者所有，未经授权不得转载。证，通过对token的处理，查找到拥有该未经授权，禁止复制转载。【访问 www.tangshuang.net 获取更多精彩内容】token的实际用户，从而确定了将对哪一【转载请注明来源】【本文受版权保护】个用户进行信息更新操作。

国内大部分API对PUT、DELETE请【作者：唐霜】【访问 www.tangshuang.net 获取更多精彩内容】求进行了阉割，更不用提HEAD、PACT著作权归作者所有，禁止商业用途转载。【原创内容，转载请注明出处】H、OPTIONS请求。实际上，国内大部【作者：唐霜】【访问 www.tangshuang.net 获取更多精彩内容】分开放API仅支持GET和POST两种，【本文受版权保护】【原创不易，请尊重版权】部分API支持将app key信息通过h【访问 www.tangshuang.net 获取更多精彩内容】转载请注明出处：www.tangshuang.neteader进行发送。在面对这种情况下，我【转载请注明来源】【版权所有，侵权必究】们不得不抛弃标准的RESTful规范，在【转载请注明来源】转载请注明出处：www.tangshuang.neturl中加入get、add、update【关注微信公众号：wwwtangshuangnet】本文作者：唐霜，转载请注明出处。、delete等动作词汇，以补充由于请求【转载请注明来源】本文作者：唐霜，转载请注明出处。支持不完善带来的动作区分问题。如果仅支持未经授权，禁止复制转载。转载请注明出处：www.tangshuang.netGET和POST，那么所有需要保密的数据【版权所有】唐霜 www.tangshuang.net【版权所有】唐霜 www.tangshuang.net，绝对不可以用GET来进行请求，而必须用著作权归作者所有，禁止商业用途转载。【访问 www.tangshuang.net 获取更多精彩内容】POST。

参考文献：

《理解RESTful架构》《RESTful API 设计指南》

【原创内容，转载请注明出处】著作权归作者所有，禁止商业用途转载。

《好RESTful API的设计原则》

【原创不易，请尊重版权】本文版权归作者所有，未经授权不得转载。【访问 www.tangshuang.net 获取更多精彩内容】【原创不易，请尊重版权】

《我所理解的RESTful Web API【本文首发于唐霜的博客】【未经授权禁止转载】 [设计篇]》

【未经授权禁止转载】转载请注明出处：www.tangshuang.net【访问 www.tangshuang.net 获取更多精彩内容】

《https工作原理》

【作者：唐霜】原创内容，盗版必究。原创内容，盗版必究。著作权归作者所有，禁止商业用途转载。

【本文首发于唐霜的博客】【作者：唐霜】著作权归作者所有，禁止商业用途转载。转载请注明出处：www.tangshuang.net【访问 www.tangshuang.net 获取更多精彩内容】原创内容，盗版必究。本文版权归作者所有，未经授权不得转载。著作权归作者所有，禁止商业用途转载。本文版权归作者所有，未经授权不得转载。著作权归作者所有，禁止商业用途转载。【关注微信公众号：wwwtangshuangnet】【转载请注明来源】【版权所有，侵权必究】【版权所有】唐霜 www.tangshuang.net【未经授权禁止转载】未经授权，禁止复制转载。【未经授权禁止转载】【原创内容，转载请注明出处】【关注微信公众号：wwwtangshuangnet】【本文首发于唐霜的博客】原创内容，盗版必究。【版权所有，侵权必究】未经授权，禁止复制转载。【本文受版权保护】

2015-11-25 18510

唐霜

基于HTTPS的REST API设计初探

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

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

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

4. 版本

5. HTTP响应码

6. 返回值结构

7. 鉴权

参考文献：

为价值买单，打赏一杯咖啡

声明

关于

生态