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元型确实很精彩。