RESTful架构，一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用
起源 REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的
Fielding将他对互联网软件的架构原则，定名为REST，即Representational State Transfer的缩写。这个词组的翻译是"表现层状态转化"，如果一个架构符合rest原则，我们就称它为restful架构
资源(resources)
rest翻译为表现层状态转化，它没有指名是谁的表现层，缺乏主语，在这里，我们用资源当做主语，即为资源的表现层状态转化。
所谓资源，就是网络上的一个实体，它可以是一张图片，一段文本。。。我们可以用一个url指向它，用户通过url就能访问到这个资源。
普及两个概念 uri与url，uri（统一资源标识符 Uniform Resource Identifier），url（统一资源定位符 Uniform Resource Locator），其中url是uri的子集
表现层(representation)
资源是一种信息实体，它可以有多种外在表现，比如文本可以以txt格式表现，也可以用html，json，xml格式表现，我们把资源具体呈现出的形式叫做它的表现层。
uri指向资源，但不代表资源的形式，http头部中的accept和content-type等表达了资源的形式
状态转化(state transfer)
访问一个uri，就代表客户和服务器发生了一个交互，这个过程会涉及到数据和状态的变化。
互联网通信协议http协议，是无状态的，不能记录资源的各种状态，资源的状态保存在服务器端，如果要操作服务器上的资源，就要通过一些手段，让服务器知道，从而让服务器的资源发生状态转化，这个变化是建立在表现层之上的，就是表现层状态转化。
客户端使用的手段，只能是http协议，http协议里有很多操作方式的动词比如get，post，put，delete，它们对应了四种基本操作，get用来获取资源（查），post用来新建资源（增）或者修改资源（改），put用来更新资源（改），delete用来删除资源（删）。
综上
restfull架构即为
每个url指向一种资源，客户端和服务器之间传递资源的某种表现层，客户通过4个http动词，对服务器资源进行操作，实现服务器资源表现层状态转化
常见误区
url中含有动词，比如/users/update/1,其中update是动词（手段），这个url就不满足restful架构，正确的写法是/user/1，然后用put方式或post方式
url中带有版本号，不同版本，可以理解为同一资源的不同表现形式，可以把版本号放到http头信息中，从url剔除
restful api设计
一、协议
api与用户的通信协议采用http协议
二、域名
尽量将api部署到专用域名下，比如 http://api.test.com。如果api不多且比较简单，不太会进一步扩展，也可以放到主域名下，比如http://test.com/api/...
三、版本(version)
将版本号放到http头信息中，也有说法说版本号放到url中更方便直接，github的是放在http头信息里的
四、路径(endpoint)
路径又称“终点”(endpoint)，表示api具体网址，在restful架构中，每个网址代表一种资源(resource)，所以网址中不能有动词，比如说一个api提供动物园zoo信息，其中包括各种动物以及雇员信息，符合restful架构的url可如下设计
- http://api.test.com/zoos
- http://api.test.com/animals
- http://api.test.com/employees
- http://api.test.com/zoo/1
五、http动词
对于资源的具体操作类型，由http动词表示，常用的http动词如下
- get(select)，从服务器获取资源（一项或多项）
- post(create)，在服务器新建一个资源
- put(update)，在服务器更新资源（客户端提供改变后的完整资源）
- patch(update)，在服务器更新资源（客户端提供改变的属性）比如svn中针对修改打patch操作
- delete(delete)，从服务器删除资源
两个不常用http动词
- head，获取资源元数据
- options，获取信息，关于资源的哪些属性是客户端可以修改的
例子如下
- get /zoos，获取所有动物园
- post /zoos，新建一个动物园
- get /zoo/id，获取某个指定动物园的信息
- put /zoo/id，更新某个指定动物园信息（提供该动物园修改后的完整信息）
- patch /zoo/id，更新某个指定动物园信息（提供该动物园部分信息）
- delete /zoo/id, 删除某个动物园
- get /zoos/id/animals，获取指定动物园的所有动物
- delete /zoos/id/anamal/id，删除指定动物园的指定动物
六、信息过滤(filter)
如果资源数量过多，服务器不好一次性全部返回给用户，api应该提供参数，过滤返回结果，比如指定筛选条件，排序，分页，限制返回数量等
- ?animalType=1，指定筛选条件
- ?sort=age&order=desc，排序
- ?page=2&perPage=10，分页
- ?limit=10，限制返回数量
参数设计允许冗余，即允许api路径与url参数偶尔重复，比如 get /zoos/id/animals与 get /animals?zooId=id含义相同
七、状态码(status code)
服务器向用户返回的状态码和提示信息，常见的列表以下
- 200 OK - [get]，服务器成功返回用户请求的数据，该操作是幂等的(idempotent)
- 201 CREATED - [post/put/patch]，用户新建或修改数据成功
- 202 ACCEPTED - [*]，表示请求已进入后台排队（异步任务）
- 204 NO CONTENT - [delete]，用户数据删除成功
- 400 INVALID REQUEST - [post/put/patch]，用户发出的请求错误，服务器没有进行新建或修改数据的操作，该操作幂等
- 401 Unauthorized - [*]，用户没有权限（令牌，用户，密码错误）
- 403 Forbidden - [*]，表示用户得到授权（与401错误相对），但是访问是被禁止的
- 404 NOT FOUND - [*]，用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作幂等
- 406 Not Acceptable - [get]，用户请求的格式不可得（比如用户请求json格式，但是只有xml格式）
- 410 Gone - [get]，用户请求的资源被永久删除，且不会再得到
- 500 INTERNAL SERVER ERROR - [*]，服务器发生错误，用户将无法判断发出的请求是否成功
八、错误处理(error handling)
如果状态码是4xx，应该向用户返回错误信息，一般来说，返回的信息中将error作为键名，出错信息作为键值即可
九、返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范
- get /collection 返回资源对象的列表（数组）
- get /collection/resource 返回单个资源对象
- post /collection 返回新生成的资源对象
- put /collection/resource 返回完整的资源对象
- patch /collection/resource 返回完整的资源对象
- delete /collection/resource 返回一个空文档
十、hypermedia api
restful api最好做到hypermedia，即返回结果中信息丰富一点，提供链接，连向其他api方法，使得用户不用去查询文档，也知道下一步应该做什么。比如当用户向api.test.com的根目录发出请求时，得到的文档包含以下结果
{
"link":{ "rel": "collection http://api.test.com/zoos",
"href": "http://api/test.com",
"title": "list of zoos",
"type": "application/vnd.yourformat+json"
} }
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么api，rel代表这个api与当前网址的关系（collection关系，并给出该collection网址），href表示api路径，title表示api的标题，type表示返回类型。
hypermedia api的设计也被称为HATEOAS,github的api就是这种设计，请求github的api会得到一个所有可用api网址列表
{ "current_user_url": "https://api.github.com/user", "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}", "authorizations_url": "https://api.github.com/authorizations", "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}", "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}", "emails_url": "https://api.github.com/user/emails", "emojis_url": "https://api.github.com/emojis", "events_url": "https://api.github.com/events", "feeds_url": "https://api.github.com/feeds", "followers_url": "https://api.github.com/user/followers", "following_url": "https://api.github.com/user/following{/target}", "gists_url": "https://api.github.com/gists{/gist_id}", "hub_url": "https://api.github.com/hub", "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}", "issues_url": "https://api.github.com/issues", "keys_url": "https://api.github.com/user/keys", "notifications_url": "https://api.github.com/notifications", "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}", "organization_url": "https://api.github.com/orgs/{org}", "public_gists_url": "https://api.github.com/gists/public", "rate_limit_url": "https://api.github.com/rate_limit", "repository_url": "https://api.github.com/repos/{owner}/{repo}", "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}", "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}", "starred_url": "https://api.github.com/user/starred{/owner}{/repo}", "starred_gists_url": "https://api.github.com/gists/starred", "team_url": "https://api.github.com/teams", "user_url": "https://api.github.com/users/{user}", "user_organizations_url": "https://api.github.com/user/orgs", "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}", "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}" }
从上面可以看到，如果想获取当前用户的信息,应该去访问api.github.com/user，会得到如下返回结果
{ "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3/users/#get-the-authenticated-user" }
返回结果给出了服务器的提示信息，以及相应文档地址
十一、其他
api的身份认证可以使用Oauth框架
服务器返回的数据格式，尽量使用json，xml