REST API design rulebook 笔记（一）
????? 最近在看一本OReilly的书，很薄，但是对REST API设计有很多操作性很强的意见。由于很多原则很简单，解释说明部分就不翻译了。边读边写，记录一下读书笔记。
? ? ? 前言和第一章都比较简单，略去。
?
? ? ? 第二章 URI设计
? ? ? URIs
? ? ? ? ? ?REST接口使用URI寻址一个resource。URI是接口的唯一标识。
? ? ? URI格式
? ?原则：斜杠(/)用于分层
? ? ? ? ? ?原则：末尾不包含/
? ? ? ? ? ?原则：连字符-可以使URI可读性更好
? ? ? ? ? ?原则：下划线_不要使用
? ? ? ? ? ?原则：优先使用小写
? ? ? ? ? ?原则：不要包含扩展名
? ? ? 在Web中的URI里，点号(.)一般用于区分文件名和扩展名。REST 接口不应该用URI中的虚文件名指明希望的格式。而是应该用Content-Type头，用media type，告诉对方如何处理请求体/响应体的内容。后面会讲到Media type的更多内容。
? ? ? P.S 为简化连接和更易调试，REST接口可以支持查询参数做为media type协商，见后续。“原则：支持用查询参数进行media type协商”。
? ? ? URI标准设计
? ?原则：在接口中使用一致的子域名
? ?原则：客户端开发指南中使用一致的子域名做为入口。
? ? ? Resource建模
? ? ??URI路径表示REST接口的resource模型，斜杠分割的路径片段与层级内的resource有一致的含义。比如，URI：
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet?
表明，如下URI都可以确定一个可寻址的resource
http://api.soccer.restapi.org/leagues/seattle/teams?
http://api.soccer.restapi.org/leagues/seattle?
http://api.soccer.restapi.org/leagues?
http://api.soccer.restapi.org?
Resource建模是一个确立API关键概念的过程。这个过程类似于对一个关系数据库系统的数据建模，或对一个面向对象系统的对象建模。
在确定URI路径前，首先应该先了解一下REST API resource的类型。
?
? ? ??Resource 元型
? ? ? 类似于设计模式，resource有助于我们的设计与一般REST接口设计表达一致的结构和行为。REST API包含四种元型：document, collection, store, controller.
? ? ? ?为了对客户端暴露一个结构清晰表达清楚的resource模型，REST接口应该为每个Resource使用一种元型。为一致性目的，resource也应该避免混杂两种以上的元型。反之，则应该设计独立的resource，通过链接表达这种关系。
?
? ? ? ?Document
? ? ? 一个document resource是一个单数名词，类似于一个对象实例或数据库的一条记录。一个典型的document的状态表述(representation)应该包含两部分，一个是本对象各字段的值，一个是其他关联对象的链接。由各字段值和链接组成的document元型，可以看作是其他元型的“元元型”，其它三种resource元型，可以看作是特殊的document元型。
以下都是document resource的URI
http://api.soccer.restapi.org/leagues/seattle?
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet?
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/mike?
? ? ? document可以有子resource，用于描述详细的附属信息。子resource可以有不同的resource类型，它们可以同属同一个上层resource，所以，REST API逻辑上的根resource可以是一个document，这个称为docroot .?
?
? ? ? Collection
? ? ? Collection resource是服务端控制的resource的目录。客户端可以请求向其中加入一个新的resource. Collection负责选择或创建新的resource. Collection决定包含哪些resource，并且为每个被包含的resource提供URI.
例子：
http://api.soccer.restapi.org/leagues?
http://api.soccer.restapi.org/leagues/seattle/teams?
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players?
?
? ? ? Store
? ? ? Store是由客户端控制的resource的仓库。Store resource提供API，由客户端放入、取出，并由客户端决定何时删除。Store并不创建新的resource，因此，store不产生新的URI，每一个store resource的URI由客户端在放入时确定。
下面这个例子是，一个用户(id 1234)通过客户端程序把名字为alonso的resource放入自己的收藏夹。
PUT /users/1234/favorites/alonso?
?
? ? ? Controller
? ? ? Controller resource 有程序含义。Controller resource类似于可执行程序，有入参和返回值，或者输入输出。REST API依赖controller resource执行特定的操作，这些操作不可以是标准方法(创建、获取，更新，删除，即crud)。典型的controller名字在URI的末尾，没有子resource。下例中，客户端给一个用户重发警告：
POST /alerts/245743/resend
?
? ? ? 注：这段resource元型确实很精彩。
?
