为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译

前言

这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Heroku 平台的 API 设计指引 Heroku 平台 API 指引

这篇指南除了详细介绍现有的 API 外,Heroku 将来新加入的内部 API 也会符合这种设计模式,我们希望非 Heroku 员工的API设计者也能感兴趣。

我们的目标是保持一致性,专注业务逻辑同时避免过度设计。我们一直试图找出一种良好的、一致的、显而易见的 API 设计方法,而并不是所谓的"最终/理想模式"。

我们假设你熟悉基本的 HTTP+JSON API 设计方法,所以本篇指南并不包含所有的 API 设计基础。

我们欢迎你为这篇指南做贡献


返回合适的状态码

为每一次的响应返回合适的HTTP状态码。 好的响应应该使用如下的状态码:

  • 200GET请求成功,及DELETEPATCH同步请求完成,或者PUT同步更新一个已存在的资源

  • 201POST 同步请求完成,或者PUT同步创建一个新的资源

  • 202POSTPUTDELETE,或PATCH请求接收,将被异步处理

  • 206GET 请求成功,但是只返回一部分,参考:上文中范围分页

使用身份认证(authentication)和授权(authorization)错误码时需要注意:

  • 401 Unauthorized: 用户未认证,请求失败

  • 403 Forbidden: 用户无权限访问该资源,请求失败

当用户请求错误时,提供合适的状态码可以提供额外的信息:

  • 422 Unprocessable Entity: 请求被服务器正确解析,但是包含无效字段

  • 429 Too Many Requests: 因为访问频繁,你已经被限制访问,稍后重试

  • 500 Internal Server Error: 服务器错误,确认状态并报告问题

对于用户错误和服务器错误情况状态码,参考: HTTP response code spec

提供全部可用的资源

提供全部可显现的资源 (例如: 这个对象的所有属性) ,当响应码为200或是201时返回所有可用资源,包含 PUT/PATCH 和DELETE
请求,例如:

$ curl -X DELETE \
https://service.com/apps/1f9b/domains/0fd4 HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
...
{
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}

当请求状态码为202时,不返回所有可用资源,例如:

$ curl -X DELETE \
https://service.com/apps/1f9b/dynos/05bd HTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
...
{}

在请求的body体使用JSON格式数据

在 PUT/PATCH/POST 请求的正文(request bodies)中使用JSON格式数据,而不是使用 form 表单形式的数据。这与我们使用JSON格式返回请求相对应,例如:

$ curl -X POST https://service.com/apps \
-H "Content-Type: application/json" \
-d '{"name": "demoapp"}' {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "demoapp",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
...
}

使用统一的资源路径格式

资源名(Resource names)

使用复数形式为资源命名,除非这个资源在系统中是单例的 (例如,在大多数系统中,给定的用户帐户只有一个)。 这种方式保持了特定资源的统一性。

行为(Actions)

好的末尾不需要为资源指定特殊的行为,但在特殊情况下,为某些资源指定行为却是必要的。为了描述清楚,在行为前加上一个标准的actions

/resources/:resource/actions/:action

例如:

/runs/{run_id}/actions/stop

路径和属性要小写

为了和域名命名规则保持一致,使用小写字母并用-分割路径名字,例如:

service-api.com/users
service-api.com/app-setups

属性也使用小写字母,但是属性名要用下划线_分割,以便在Javascript中省略引号。 例如:

service_class: "first"

支持方便的无id间接引用

在某些情况下,让用户提供ID去定位资源是不方便的。例如,一个用户想取得他在Heroku平台app信息,但是这个app的唯一标识是UUID。这种情况下,你应该支持接口通过名字和ID都能访问,例如:

$ curl https://service.com/apps/{app_id_or_name}
$ curl https://service.com/apps/97addcf0-c182
$ curl https://service.com/apps/www-prod

不要只接受使用名字而放弃了使用id。

最小化路径嵌套

在一些有父路径/子路径嵌套关系的资源数据模块中,路径可能有非常深的嵌套关系,例如:

/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}

推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中,dyno属于app,app属于org可以表示为:

 
/orgs/{org_id}
/orgs/{org_id}/apps
/apps/{app_id}
/apps/{app_id}/dynos
/dynos/{dyno_id} 原文:
https://segmentfault.com/a/1190000002512493

HTTP API 设计指南(请求部分)的更多相关文章

  1. RESTful API 设计指南 (转)

    RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...

  2. 来自HeroKu的HTTP API 设计指南(中文版)

    原文转自:http://get.jobdeer.com/343.get 来自HeroKu的HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国内 ...

  3. RESTFul API设计指南及使用说明

    RESTFul API设计指南及使用说明 一. 协议 API与用户的通信协议,使用HTTP协议. 二. 域名 应尽量将API部署在专用域名之下(http://api.example.com) 也可以将 ...

  4. RESTful API 设计指南,RESTful API 设计最佳实践

    RESTful API 设计指南,RESTful API 设计最佳实践 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). ...

  5. Rest Framework简介 和 RESTful API 设计指南

    使用Django Rest Framework之前我们要先知道,它是什么,能干什么用? Django Rest Framework 是一个强大且灵活的工具包,用以构建Web API 为什么要使用Res ...

  6. [置顶] 来自 HeroKu 的 HTTP API 设计指南(中文版)

    转载:http://get.jobdeer.com/343.get 来自 HeroKu 的 HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国 ...

  7. 理解RESTful架构——Restful API设计指南

    理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...

  8. 组件接口(API)设计指南-文件夹

    组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...

  9. API设计指南(译)

    API的设计在软件系统中的重要性不言而喻,在swift.org上看到一篇“API Design Guidelines”,虽然是就Swift而言,但对于其它语言也有不少可以借鉴的地方,在这里粗略翻译一二 ...

随机推荐

  1. iOS - UIMenuController

    前言 NS_CLASS_AVAILABLE_IOS(3_0) __TVOS_PROHIBITED @interface UIMenuController : NSObject 1.UIMenuCont ...

  2. Java:集合,Collections工具类用法

    Collections工具类提供了大量针对Collection/Map的操作,总体可分为四类,都为静态(static)方法: 1. 排序操作(主要针对List接口相关) reverse(List li ...

  3. C#的MD5哈希值计算

    MD5哈希值计算:(仅仅是记录一下) /// <summary> /// 获取字符串的MD5值 /// </summary> /// <param name=" ...

  4. Wireshark分析网络慢

        tcp.analysis.retransmission tcp.flags.reset==1

  5. 【Android】17.2 Activity与Local Service的绑定

    分类:C#.Android.VS2015: 创建日期:2016-03-03 一.简介 如果服务是你的应用程序所私有的,即服务(Service)与客户端(Activity)都在同一个项目中(大部分应用程 ...

  6. 关于navigationBar的颜色计算与默认透明度

    NavigationBar的默认透明度为85% 颜色叠加计算公式: RGB需要分开计算,以叠加白色背景为例: 原始颜色(217,10,20) 设置透明度85% 计算过程: R=217 + (255-2 ...

  7. app 图标规格参考表

    转自:http://www.cocoachina.com/appstore/top/2012/1105/5031.html 像我一样记不住iOS应用图标像素尺寸的开发者不在少数,我经常需要查询不同设备 ...

  8. 李洪强iOS开发之-FMDB的用法

    // //  ViewController.m //  04 - FMDB的用法 // //  Created by 李洪强 on 2017/6/6. //  Copyright © 2017年 李洪 ...

  9. flask celery 使用方法

    一.安装 由于celery4.0不支持window,如果在window上安装celery4.0将会出现下面的错误flask_clery 你现在只能安装pip install celery==3.1 二 ...

  10. python——内置函数和lambda匿名函数

    内置函数 接下来,我们就一起来看看python里的内置函数.截止到python版本3.6.2,现在python一共为我们提供了68个内置函数.它们就是python提供给你直接可以拿来使用的所有函数.这 ...