最近在做一个客户端程序的架构设计，看了下服务器给的初版接口文档，发现做的非常不好，接口设计没有任何规范可言，也没有规律。着手修改了一下，给出了一些修改意见。
现在把这些心得分享给大家，希望大家以后再设计接口时，也能遵循这些规范，让我们的程序员在coding的时候能够更加顺手。
所谓RESTful架构，就是 Representational State Transfer。但是实际上这个词组少了一个主语 也就是Resources.资源的意思。合起来就是 资源 表现层的状态转化。
比较绕口不好理解。我来解释一下。
资源大家肯定都懂。比如网络上的文字 图片 视频 等等都是资源。
Representational 表现层，就是对这些资源的表现形式。比如文本，可以用txt 用html 用xml 用json来表示。图片可以用jpg png等等 这些东西就是表现层。
到这里，要注意一下，我们的uri。只能代表资源的实体，而不能代表资源的表现形式。比如我们很多网页的地址后面会跟一个 .html。实际上这个是非常不好的
风格。.html 是代表资源的表现形式。因为这是一种格式。但是uri 只能表示资源的位置。所以这个表现形式 .html 应该放在http请求头的accept和Content-Type
这边。这两个字段才是对Representational 的表述。
最后说一下这个 State Transfer ，在http的世界中 对资源uri的操作 只能是 put delete get 和post。这个就代表了资源的转化。
下面来举例说明怎么设计具有restful 风格的api 或者uri。
1.URI 里面不得有动词。
动词应该放到http头中。比如说 /news/show/1
这个URI就设计的不好。因为show是动词。所以这个URI 应该设计成 /news/1. URI只能代表资源。
然后这个show 就放在http协议的头部中 也就是get方法即可。
2.如果某些操作 put delete get post这四个http 词汇表现不了怎么办。
比如说 要设计一个 a玩家 向b玩家汇款 200元 这个操作。
有的人设计的时候就是
POST /accounts/a/transfer/200/to/b
但RESTful 风格 让我们不要放动词在uri里面所以这个接口 我们应该
POST /transaction HTTP/1.1
Host: 127.0.0.1
from=a&to=b&amount=200
这样风格就完美。
3.版本号如何表示。
服务器的接口经常升级 所以每一次的接口都会有版本号。有的时候客户端在访问的时候 要把自己客户端使用的服务器接口版本号发过去 让服务器决定如何相应。
很多人会这么设计
http://www.burning.com/app/1.0/test
但实际上这样做风格也很差。我们应当把版本号放在。http头的Accept 字段中。
4.怎么一次请求多个资源。这种uri应该如何设计。
比如我们可以这样
REQUEST: GET /hotel/656bcee2-28d2-404b-891b/classification,name HTTP/1.1 Host: localhost User-Agent: xLightweb/2.6 Accept: application/x-www-form-urlencoded RESPONSE: HTTP/1.1 200 OK Server: xLightweb/2.6 Content-Length: 43 Content-Type: application/x-www-form-urlencoded; charset=utf-8 classification=Comfort&name=Central
要注意的是
RESTful HTTP服务端程序必须根据HTTP规范返回状态码。状态码的第一个数字标识返回类型，1xx表示临时响应，2xx表示成功响应 ，3xx代表转发，4xx表示客户端错误，5xx代表服务端错误。使用错误的响应码，或者总返回200响应，并在消息主体中包含特定应用程序的响应，这两种做法都是不好的实践。