API的HTTP状态码设计

一、现状：

前天与后端开发人员讨论了API接口的设计。有以下三种方案：

• 1、原始HTTTP协议
  HTTP状态码就是该Request的状态码，不应该与后端业务混在一起（这也是一部分人使用该方案的理由）。比如200表示该Request成功了，具体业务有没有操作成功还需要在response body里再标记，比如1表示操作成功，0表示操作失败。

• 2、HTTP协议 RESTful 风格
  充分利用HTTP状态码，比如200就是该操作成功，定义一个5xx表示业务操作失败，如果该业务失败有多种情况则在response body里再标记。

• 3、SOAP

三者都可以实现，当然是推荐使用2，现在各大网络框架和大的开发平台API 基本都是这样的。

二、RESTful 中http code 设计

• 1、标准的200的含义
  请求已成功，请求所希望的响应头或数据体将随此响应返回。这句话的意思不就是业务操作成功嘛。

• 2、RESTful 对200 多了一条要求：幂等性
  幂等的意思是请求成功执行所得到的的结果不依赖于该方法被执行的次数。也就是说如果HTTP状态码是200，那么reponse body的报文结构应该只有一种。

三、RESTful 优点

• 1．面向资源的接口设计
  所有的接口设计都是针对资源来设计的，也就很类似于我们的面向对象和面向过程的设计区别，只不过现在将网络上的操作实体都作为资源来看待，同时URI的设计也是体现了对于资源的定位设计。这样更符合自然语义。简化了开发者的不良设计。例如DELETE /zoos/ID：删除某个动物园 200 就是删除成功，非200就是 删除失败。符合自然语义。使得客户端的处理逻辑变得简单。

• 2．抽象操作为基础的CRUD

  这点很简单，Http中的get,put,post,delete分别对应了read,update,create,delete四种操作，最大限度的利用了Http最初的应用协议设计理念。

• 3．Http是应用协议而非传输协议
  SOAP协议对于消息体和消息头都有定义，消息头的可扩展性高，但是也由于SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。 SOAP 把HTTP当做传输层来使用了，自己封装了一套应用协议。而RESTful 本身不是协议，是一种HTTP协议的使用规范，使得HTTP协议就是作为应用层来使用。简洁易用。

四、RESTful vs JSON-RPC

JSON-RPC是一个无状态且轻量级的远程过程调用(RPC)协议。 本规范主要定义了一些数据结构及其相关的处理规则。它允许运行在基于socket,http等诸多不同消息传输环境的同一进程中。其使用JSON（RFC 4627）作为数据格式。

Web Service 也提出了好久了, 那么究竟什么是 Web Service ?

简单地说, 也就是服务器如何向客户端提供服务.

常用的方法有:

RPC 所谓的远程过程调用 (面向方法)
SOA 所谓的面向服务的架构(面向消息)
REST 所谓的 Representational state transfer (面向资源)

JSON-RPC协议描述

json-rpc协议非常简单，发起远程调用时向服务端传输数据格式如下：

{ “method”: “sayHello”, “params”: [“Hello JSON-RPC”], “id”: 1}

参数说明：

method： 调用的方法名

params： 方法传入的参数，若无参数则传入 []

id ： 调用标识符，用于标示一次远程调用过程

服务器其收到调用请求，处理方法调用，将方法效用结果效应给调用方；返回数据格式：

{
“result”: “Hello JSON-RPC”,
“error”: null,
“id”: 1
}

http://wiki.geekdream.com/Specification/json-rpc_2.0.html
http://gubaojian.blog.163.com/blog/static/1661799082012101439591/
http://www.cnblogs.com/mindsbook/archive/2009/11/17/web_service_RESTvsRPC.html