RESTful Web API 风格

RESTful是一种架构风格。基于RESTful Web API的设计思想，本文档的Web API设计风格是Dosser风格。

Dosser风格

Dosser风格是领域特定的语意表达(DOmain-Specific SEmantic Representation)。 Dosser的响应包括以下部分：

  1. HTTP 状态码

    参考HTTP 状态码。

  2. meta

    2.1. criteria

     类型为Hash。将请求的参数、条件返回给客户端，便于调试。出于安全考虑，密码不应该回传。处于性能考虑，上传文件的内容不应该回传。

    2.2. timestamp

     类型为整数。服务器的时间戳，是1970年1月1日到请求的秒数。

    2.3. request_id

     类型为字符串。服务器的请求ID，便于调试。

  3. success

    类型为布尔值，true 或者 false 。

    • true 表示请求处理成功，对应的HTTP状态码通常是200-399之间的值。
    • false 表示请求处理失败，对应的HTTP状态吗通常是400-599之间的值。

  4. code

    类型为字符串。表达成功状态、失败原因的字符串。这个字符串与客户端程序员约定的，因此双方可以硬编码到代码中，从而对错误的情况进行进一步处理。

    • 如果 success = true，则 code = success 。
    • 如果 success = false，则 code = failure 或者 failure- 。其中 是双方约定小写字符串，用减号分隔单词。

  5. message

    类型为字符串，对最终用户友好的文本消息，可用于之间呈现给最终用户。

  6. size

    类型为整数。

    • 符合条件的所有资源的数量。
    • 如果遇到分页查询的情况，此处应该返回所有匹配的资源的数量，而不是返回的当前页的资源的数量。
    • 如果是创建单个资源，成功返回1，失败返回0。
    • 如果是批量创建资源，返回成功创建的资源的数量。
    • 如果是更新单个资源，成功返回1，失败返回0。
    • 如果是批量更新资源，返回成功更新的资源的数量。
    • 如果是删除单个资源，成功返回1，失败返回0。
    • 如果是批量删除资源，返回成功删除的资源的数量。

  7. collection

    类型为数组。数组的每个元素为Hash，表示一个资源。 7.1. 模型的links属性

     每个模型除了自己的基本属性外，还可以有links属性，类型为数组，数组的每个元素是Hash，每个Hash有以下的属性：
 - href: 链接的URL。
 - rel:  描述关系的关键词。首先遵循[Web Linking](http://tools.ietf.org/html/rfc5988)。其次使用 dosser/{action}-{resource}格式，如：dosser/create-confirmation-code、dosser/create-session。
 - type: 规定被链接文档的 MIME 类型。如：text/json、text/xml、application/json、application/xml、application/json+dosser、application/xml+dosser。
    • 符合条件的所有资源的列表。
    • 如果遇到分页查询的情况，此处应该返回当前页的资源的列表。
    • 如果是创建单个资源，成功返回1个资源，失败返回空数组。
    • 如果是批量创建资源，返回成功创建的资源的数组。
    • 如果是更新单个资源，成功返回1个更新后的资源，失败返回空数组。
    • 如果是批量更新资源，返回成功更新的资源的数组。
    • 如果是删除单个资源，返回空数组。
    • 如果是批量删除资源，返回空数组。

  8. errors

    类型为Hash。

    • 键和请求的参数名一一对应。
    • 值必须是字符串的数组。每个字符串是一个独立的出错消息，并且消息文本中不包含字段名称。