帮酷LOGO
  • 显示原文与译文双语对照的内容
文章标签:设计  gui  Sheet  设计指南  Api设计  指南  API  GUID  
API Design Guidelines and Best Practices Cheat Sheet

  • 源代码名称:api-cheat-sheet
  • 源代码网址:http://www.github.com/RestCheatSheet/api-cheat-sheet
  • api-cheat-sheet源代码文档
  • api-cheat-sheet源代码下载
  • Git URL:
    git://www.github.com/RestCheatSheet/api-cheat-sheet.git
  • Git Clone代码到本地:
    git clone http://www.github.com/RestCheatSheet/api-cheat-sheet
  • Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/RestCheatSheet/api-cheat-sheet
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
  • 请参阅:平台构建备忘单。

    API设计备忘单

    用mind--as中的消费者构建 API,以它的自身的优势。

    • 不是针对特定的用户界面。
    • 拥抱每个端点( 请参阅 #5, 6 & 7 )的灵活性/灵活性。
    • 即使你必须模拟一个示例 UI,也可以以使用你自己的dogfood 。

    使用收集隐喻。

    • 每个资源的两个 url ( 终结点):
      • 资源集合( 比如 。/订单)
      • 集合中的单个资源( 比如 。 /orders/{orderId}).
    • 使用复数形式('订单'而不是'订单') 。
    • 以id作为URL节点的备用资源名称( 比如 。 /orders/{orderId}/items/{itemId})
    • 尽可能短地保留 url 。 最好每个URL不超过三个节点。

    使用名词作为资源名称( 比如 。 不要在url中使用动词) 。

    使资源表示有意义。

    • "无裸 id 在响应中没有嵌入普通 id 。 使用链接和参照对象。
    • 设计资源表示形式不只是表示数据库表。
    • 合并表示形式不要将关系表作为两个id公开。

    支持集合中的筛选。排序和分页。

    支持链接扩展关系。 允许客户端扩展响应中包含的数据,包括附加的表示,或者者除这里之外的链接。

    支持资源上的字段投影。 允许客户端减少响应中返回的字段数。

    使用HTTP方法名称表示某些内容:

    • POST - 创建和其他非幂运算。
    • 放置- 更新。
    • 获取- 读取资源或者集合。
    • 删除- 删除资源或者集合。

    使用HTTP状态代码有意义。

    • 200 - 成功。
    • 201 - 创建成功,成功创建了新资源。 包含一个'位置'头,带有指向新创建资源的链接。
    • 400 - 错误请求。如无效的JSON等数据问题。
    • 404 - 找不到资源在获取时找不到资源。
    • 409 - 冲突。重复的数据或者无效的数据状态。

    在表示中使用 ISO 8601 timepoint格式。

    使用链接策略考虑连通性。 一些常见的示例包括:

    使用 OAuth2插件保护你的API 。

    • 使用承载令牌进行身份验证。
    • 要求 HTTPS/TLS/SSL 访问你的api 。 OAuth2承载令牌要求它。 通过HTTP进行未加密的通信允许简单的eavesdroppping和模拟。

    使用 Content-Type 协商来描述传入请求负载。

    例如,假设你正在进行分级,包括一个拇指上/拇指下降和五个星级级别。 你有一个创建分级的路由: POST/分级

    如何区分传入数据和服务,以便确定它是哪一种分级类型: 大拇指向上或者五星?

    诱惑是为每个分级类型创建一个路由: 邮寄/ratings/five_star 和邮资POST后的/ratings/thumbs_up

    但是,通过使用 Content-Type 协商,我们可以使用相同的/分级路由。 通过将 Content-Type的头设置为 Content-Type:的请求, application/vnd.company.rating.thumbsup 或者 Content-Type: application/vnd.company.rating.fivestar 服务器可以确定如何处理传入速率数据。

    版本化过程。但是,如果版本控制,则使用Accept标头而不是URL中的版本控制。

    • 通过URL的版本化表示'平台'版本,整个平台必须同时被版本化,以启用链接策略。
    • 通过Accept标头的版本管理是对资源的版本控制。
    • 对JSON响应的添加不需要版本控制。 但是,对'必选'请求正文的添加是troublesome--and的,它可以能需要版本控制。
    • 无论what--minimize是什么,超媒体链接和版本。
    • 请注意,URL中的版本不鼓励使用,可以用作'平台'版本。 它应该显示为路径中的第一个 node,而不是版本单独的端点( 比如 。 api.example.com/v1/...).

    考虑高速缓存能力至少,使用以下响应标头:

    • ETag - 表示表示版本的任意字符串。 确保在哈希值中包含媒体类型,因为这将产生不同的表示。 ( 例如:ETag:" 686897696 a7c876b7e")
    • Date返回响应的日期和时间( ( 以RFC1123格式格式) ) 。 ( 例如:日期:Sun,06 1994年月 08: 49: GMT )
    • 缓存控制- ( 最大年龄) 响应可以缓存的最大秒数。 但是,如果响应不支持缓存,则没有缓存是值。 ( 例如:高速缓存控制:360或者高速缓存控制: 无缓存)
    • of - 如果给定了最大年龄,则包含响应过期时间的时间戳( 以RFC1123格式格式),这是日期值( 比如 ) 。 现在) 加上max年龄如果响应不支持缓存,则这里标头不存在。 ( 例如:过期:Sun,06 1994年月 08: 49: GMT )
    • 当缓存控件为'无缓存'时,这里标头也设置为'无缓存'。 否则,它不存在。 ( 例如:杂注:无缓存)
    • 最后一次修改资源本身上次修改的时间戳。 ( 例如:上次修改:Sun,06 1994年月 08: 49: GMT )

    确保获取。放置和删除操作都是等幂函数。 操作不应该有副作用。



    文章标签:API  DES  设计  gui  GUID  Sheet  指南  设计指南  

    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语