对RESTful架构和RESTful API的理解

RESTful架构
REST，即Representational State Transfer的缩写。翻译是\"表现层状态转化\"。

如果一个架构符合REST原则，就称它为RESTful架构。

要理解RESTful架构，最好的方法就是去理解Representational State Transfer这个词组到底是什么意思，它的每一个词代表了什么涵义。如果你把这个名称搞懂了，也就不难体会REST是一种什么样的设计。

资源（Resources）
REST的名称\"表现层状态转化\"中，省略了主语。“表现层\"其实指的是\"资源”（Resources）的\"表现层\"。

所谓\"资源\"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址独一无二的识别符。

所谓\"上网\"，就是与互联网上一系列的\"资源\"互动，调用它的URI。

表现层（Representation）
“资源\"是一种信息实体，它可以有多种外在表现形式。我们把\"资源\"具体呈现出来的形式，叫做它的\"表现层”（Representation）。
URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的\".html\"后缀名是不必要的，因为这个后缀名表示格式，属于\"表现层\"范畴，而URI应该只代表\"资源\"的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对\"表现层\"的描述。

状态转化（State Transfer）
访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到数据和状态的变化。

互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生\"状态转化\"（State Transfer）。而这种转化是建立在表现层之上的，所以就是\"表现层状态转化\"。

客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

总结：
（1）每一个URI代表一种资源；

（2）客户端和服务器之间，传递这种资源的某种表现层；

（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现\"表现层状态转化\"。

RESTful架构有一些典型的设计误区：
1.URI包含动词，因为\"资源\"表示一种实体，所以应该是名词，URI不应该有动词，动词应该放在HTTP协议中。资源不能是动词，但是可以是一种服务。
2.URI中加入版本号
因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分。

RESTful API 设计
RESTful API是目前比较成熟的一套互联网应用程序的API设计理论
一、协议
API与用户的通信协议，总是使用HTTPs协议。
二、域名
应该尽量将API部署在专用域名之下。如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
三、版本（Versioning）
应该将API的版本号放入URL。另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。
四、路径（Endpoint）
路径又称\"终点\"（endpoint），表示API的具体网址。
五、HTTP动词
对于资源的具体操作类型，由HTTP动词表示。
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
六、过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
参数：
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /class/ID/students 与 GET /class?class_id=ID 的含义是相同的。

七、状态码（Status Codes）
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

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格式，但是只有 格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
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方法，使得用户不查文档，也知道下一步应该做什么。
https://api.github.com/

{
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}\"
}

十一、其他
（1）API的身份认证应该使用OAuth 2.0框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用 。

后续内容持续补充中！