Java for Web学习笔记（八十）：RESTful和SOAP：一般性了解

SOAP

SOAP（Simple Object Access Protocol）也算是machine to machine的鼻祖，使用WSDL（Web ServicesDescriptive Language ）进行接口描述，是一种 contract-first的设计，即先定义好接口，然后server和client分别开发。

SOAP消息开始是root element，成为SOAP Envelope，所有信息将放在信封里面。信封有可选的SOAP Header，是应用特定的信息，例如认证，然后是必选SOAP body，最后是一个可选的SOAP Fault，描述处理请求的错误。

• 必需的 Envelope 元素，可把此 XML 文档标识为一条 SOAP 消息
• 可选的 Header 元素，包含头部信息
• 必需的 Body 元素，包含所有的调用和响应信息
• 可选的 Fault 元素，提供有关在处理此消息所发生错误的信息[1]

RESTful

Representational State Transfer (REST) 比SOAP要简单多了。资源的处理一般为增删改查，对应到HTTP的POST、DELETE、PUT和GET，使用HTTP URL来描述资源。

发现机制

REST使用了HTTP，HTTP的链接提供了发现机制。下面是一个例子

----- 请求 -----GET /services/Rest/ HTTP/1.1Accept: application/json----- 响应 -----200 OKContent-Type: application/hal+json{     "_links": {          "self": { "href": "http://example.net/services/Rest" },          "account": { "href": "http://example.net/services/Rest/account" },          "order": { "href": "http://example.net/services/Rest/order" }     }}

接下来，我们就可以使用http://example.net/services/Rest/account的url去获取相关的信息，象网页一样一步一步导航。还可以通过OPTIONS方法。

----- 请求 -----OPTIONS /services/Rest/account HTTP/1.1Accept: application/json----- 响应 -----200 OKAllow: OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE{    "GET": {        "description": "Get a resource or resources",        "resourceTemplate": "http://example.net/services/Rest/account/{id}",        "parameters": {            "$select": {                "type": "array/string",                "description": "The properties to be returned for each resource.",            },           "$filter" ...        }    },    "POST" ...}

这个方法，可以通过Allow，给出不同client的权限。但是对于发现机制，有缺点：

1. 如何描述发送，并没有统一的规范
2. 允许访问的资源可能很多很多，甚至可能需要分页显示

很多web services并不提供这种发现机制，简单地可以提供一份API文档给开发人员即可。

HTTP Status Code

常用的error code如下，具体参见 RFC 7231以及httpstatuses

• 400 Bad Request，用于请求的语义错误
• 401 Unauthorized，认证授权并通过
• 403 Forbidden，虽然认证通过，但是不允许访问相关的资源
• 404 Not Found，无此资源
• 405 Method Not Allowed
• 406 Not Acceptable：请求中的Accept头不被支持
• 415 Unsupported Media Type：请求中的Content-Type不被支持，如果Content-Type和Accept不会支持，优先回复415
• 500 Internal Server Error：在处理请求的过程中出错

HTTP Method

OPTIONS

前面讲到，OPTIONS可以用于发现机制，在200OK的响应中，必须带有Allow头，例如 Allow: OPTIONS,HEAD,GET,PUT,PATCH,DELETE，某种意义上也是授权了。可选的，body带有允许使用方法的描述。如果支持PATCH，则响应还需带有Allow-Patch，通过逗号分隔表示PATCH请求所允许的media-type。

某些web service允许Cross-Origin Resource Sharing（跨域资源共享），通过使用特定的header，允许授权的浏览器应用绕过AJAX的同源策略。启动CORS，必须为所有资源支持OPTIONS请求，响应带有Access-Control-Allow-Methods头。

HEAD 和 GET

HEAD和GET唯一不同就是HEAD没有body（看看keystone就知道HEAD的用途，有时我们只是为了获取token，token是头）。

• /services/Rest/account 要求给出所有account信息
• /services/Rest/account/1075，要求给出account为1075的信息
• /services/Rest/account/1075/order，给出account为1075的信息的所有下单信息
• /services/Rest/account/1075/order/1522，给出account为1075的信息的下单1522的信息。我们也可以使用accounts或者orders给出多个账号或者多单的信息，并没有限定一个，但一个会减少url的长度。
• /services/Rest/account/1075/order/1522/item/12，给出account为1075的信息的下单1522的item 12的信息。

POST

在server上创建资源。POST的URI应为集合型的，如/services/Rest/account或者/services/Rest/account/1075/order，而不是指定的，如/services/Rest/account/1075（这时应该返回405 Method Not Allowed）。一个成功处理的POST请求，应返回201 Created，并在Location中给出所创建资源的URL。

POST是非幂等的，即多个POST会创建多个资源。

PUT

更换（修改）资源。因此用于已有的资源，如果URI是集合的，应该给出405 Method Not Allowed。对于处理成功的应答，有一点歧义，书中给出的是204 No Content，但是在openstack的keystone接口中，PUT有给出200 OK，也有给出204的。

The 204 (No Content) status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.（RFC 7231）

PUT是幂等的，多个PUT对同一个资源进行影响。如果这个资源带用last modified的时间戳，或者版本，对于严格的幂等要求，只有内容真正变更，才回去更新。有时实现会简单采用部分幂等的方式，每个PUT都回去更新时间戳或者版本。

PATCH

对资源的更改。PUT给出的更改后的全量，给PATCH只给出变更的部分。这对实现会有一定困难。

• 如果成功，响应200 OK，给出完整的修改后的实体，或者给出204 No Content。
• 如果请求没有问题，但是无法实施，例如patch会令实体无效，则相应422 Unprocessable Entity。
• 如果客户端使用If-Match 或者 If-Unmodified-Since在请求头定义前提条件，如果前提条件不满足，则回复412 Precondition Failed。
• 如果多个请求同时对一个资源进行PATCH，这是不允许的，返回409 Conflict。

PATCH是幂等。

DELETE

删除资源。可用于删除单个实体，也可以集合，但是一般web service不支持用于集合（非所期）。

• 如果成功，回复200 OK，body带有所删除的资源，或者回复204 No Content。
• 如果不能马上删除，例如正在被使用，则回复202 Accepted，同时body给出一个URL，client可以用此查询执行的状态。

如果DELETE是个软删除（将某个flag置位），多个DELETE效果是相同的，类似幂等。如果DELETE是硬删除，第二个DELETE，将会回复404 Not Found，这是非幂等的，但实际并不会产生其他的影响。

相关链接： 我的Professional Java for Web Applications相关文章