HTTP API 设计指南
上一篇:字节跳动面试经验总结,已顺利拿到offer!
返回合适的状态码
为每一次的响应返回合适的HTTP状态码. 成功的HTTP响应应该使用如下的状态码:
200
:GET
请求成功, 以及DELETE
或PATCH
同步请求完成201
:POST
同步请求完成202
:POST
,DELETE
, 或PATCH
异步请求将要完成206
:GET
请求成功, 这里只是一部分状态码: 更多
对于用户请求的错误情况,及服务器的异常错误情况,请查阅完整的HTTP状态码HTTP response code spec。
提供全部可用的资源
提供全部可显现的资源 (例如. 这个对象的所有属性) 不用考虑全部可能响应的状态码,总是在响应码为200或是201时返回所有可用资源, 包含 PUT
/PATCH
和 DELETE
请求, 例如:
$ curl -X DELETE \ https://service.com/apps/1f9b/domains/0fd4HTTP/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时,不返回所有可用资源, e.g.:
$ curl -X DELETE \ https://service.com/apps/1f9b/dynos/05bdHTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
...
{}
在请求的body体使用JSON数据
在 PUT
/PATCH
/POST
请求的body体使用JSON格式数据, 而不是使用 form 表单形式的数据. 这里我们使用JSON格式的body请求创建对称的格式数据, 例如.:
$ 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"},...
}
提供资源的唯一标识
在默认情况给每一个资源一个id
属性. 用此作为唯一标识除非你有更好的理由不用.不要使用那种在服务器上或是资源中不是全局唯一的标识,比如自动增长的id标识。
返回的唯一标识要用小写字母并加个分割线格式 8-4-4-4-12
, 例如.:
"id": "01234567-89ab-cdef-0123-456789abcdef"
提供标准的时间戳
提供默认的资源创建时间,更新时间 created_at
and updated_at
, e例如:
{..."created_at": "2012-01-01T12:00:00Z","updated_at": "2012-01-01T13:00:00Z",...
}
这些时间戳可能不适用于某些资源,这种情况下可以忽略省去。
使用ISO8601的国际化时间格式
在接收的返回时间数据时只使用UTC格式. 查阅ISO8601时间格式, 例如:
"finished_at": "2012-01-01T12:00:00Z"
使用统一的资源路径
资源命名
使用复数形式为资源命名,而不是在系统中有争议的一个单个资源 (例如,在大多数系统中,给定的用户帐户只有一个). 这种方式保持了特定资源的统一性.
形为
好的末尾展现形式不许要指定特殊的资源形为,在某些情况下,指定特殊的资源的形为是必须的,用一个标准的actions
前缀去替代他, 清楚的描述他:
/resources/:resource/actions/:action
例如.
/runs/{run_id}/actions/stop
路径和属性要用小写字母
使用小写字母并用-
短线分割路径名字,并且紧跟着主机域名 e.g:
service-api.com/users
service-api.com/app-setups
同样属性也要用小写字母, 但是属性名字要用下划线_
分割,以至于这样在javaScript语言中不用输入引号。例如.:
service_class: "first"
嵌套外键关系
序列化的外键关系通常建立在一个有嵌套关系的对象之上, 例如.:
{"name": "service-production","owner": {"id": "5d8201b0..."},...
}
而不是这样 例如:。另外,搜索公众号互联网架构师后台回复“面试”,获取一份惊喜礼包
{"name": "service-production","owner_id": "5d8201b0...",...
}
这种方式尽可能的把相关联的资源信息内联在一起,而不用改变响应资源的结构,或者展示更高一级的响应区域, 例如:
{"name": "service-production","owner": {"id": "5d8201b0...","name": "Alice","email": "alice@heroku.com"},...
}
支持方便的无id间接引用
在某些情况下,为了方便用户使用接口,在末尾提供用id标识资源,例如,一个用户想到了他在heroku平台app的名字,但是这个app的唯一标识是id,这种情况下,你想让接口通过名字和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。
构建错误信息
在网络请求响应错误的时候,返回统一的,结构化的错误信息。要包含一个机器可读的错误 id
,一个人类能识别的错误信息 message
, 根据情况可以添加一个url
,告诉客户端关于这个错误的更多信息以及如何去解决它。例如:
HTTP/1.1 429 Too Many Requests
{"id": "rate_limit","message": "Account reached its API rate limit.","url": "https://docs.service.com/rate-limits"
}
把你的错误信息格式文档化,以及这些可能的错误信息id
s 让客户端能获取到.
支持Etags缓存
在所有请求响应中包含一个ETag
头,比如,标识出返回资源的指定版本. 用户能够根据他们提供的头信息If-None-Match
,在随后的请求中检查出那些无效的。
用id来跟踪每次的请求
在每一个API响应中要包含一个Request-Id
头信息, 通常用唯一标识UUID. 如果服务器和客户端都打印出他们的Request-Id
, 这对我们的网络请求调试和跟踪非常有帮助.
按范围分页
对于服务器响应的大量数据我们应该为此分页。使用Content-Range
头传递分页请求的数据.这里有个例子详细的说明了请求和响应头、状态码,限制条件、排序以及分页处理:Heroku Platform API on Ranges.
显示速度限制状态
客户端的访问速度限制可以维护服务器的良好状态,进而为其他客户端请求提供高性的服务.你可以使用token bucket algorithm技术量化请求限制.
为每一个带有RateLimit-Remaining
响应头的请求,返回预留的请求tokens。
指定可接受头信息的版本
在开始的时候指定API版本,使用Accepts
头传递版本信息,也可以是一个自定义的内容, 例如:
Accept: application/vnd.heroku+json; version=3
最好不要给出一个默认的版本, 而是要求客户端明确指明他们要使用特定的版本.
减少路径嵌套
在一些有父路径/子路径嵌套关系的资源数据模块中, 路径可能有非常深的嵌套关系, 例如:
/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}
提供机器可读的JSON概要
提供一个机器可读的概要恰当的表现你的API.使用 prmd管理你的概要, 并且确保用prmd verify
验证是有效的。
提供人类可读的文档
提供人类可读的文档让客户端开发人员可以理解你的API。
如果你用prmd创建了一个概要并且按上述要求描述,你可以很容易的生成所有结节使用prmd doc
的Markdown文件。
除此之在详细信息的结尾,提供一个关于如下信息的API摘要:
验证授权,包含获取及使用验证tokens.
API 稳定性及版本控制, 包含如何选择所需要的版本.
一般的请求和响应头信息.
错误信息序列格式.
不同语言客户端使用API的例子.
提供可执行的示例
提供可执行的示例让用户可以直接在终端里面看到API的调用情况,最大程度的让这些示例可以逐字的使用,以减少用户尝试使用API的工作量。例如:
$ export TOKEN=... # acquire from dashboard
$ curl -is https://$TOKEN@service.com/users
如果你使用prmd生成Markdown文档, 你会自动获取一些示例在结点处。
描述稳定性
描述您的API的稳定性或是它在各种各样节点环境中的完备性和稳定性 例如. 带有 原型/开发版/产品 等标签.
更多关于可能的稳定性和改变管理的方式,查看 Heroku API compatibility policy
一旦你的API宣布产品正式版本及稳定版本时, 不要在当前API版本回退做一些不兼容的改变。如果你需要回退做一些不兼容的改变,请创建一个新的版本的API。
要求传输通道安全
要求在传输通道安全的情况下访问API,这点没什么可解释的了. 因为这不值得去争辩在什么时候使用传输通道安全访问API是好的,什么时候是不好的,只需要记住在访问API时,使用安全传输通道就行了。
使用友好的JSON输出
用户在第一次看到你的API使用情况,很可能是在命令行下使用curl
进行的。友好的输出会让他们非常容易的理解你的API,为好开发者们的方便,打印友好的JSON输出, 例如:
{"beta": false,"email": "alice@heroku.com","id": "01234567-89ab-cdef-0123-456789abcdef","last_login": "2012-01-01T12:00:00Z","created_at": "2012-01-01T12:00:00Z","updated_at": "2012-01-01T12:00:00Z"
}
而不是这样 例如:
{"beta":false,"email":"alice@heroku.com","id":"01234567-89ab-cdef-0123-456789abcdef","last_login":"2012-01-01T12:00:00Z", "created_at":"2012-01-01T12:00:00Z","updated_at":"2012-01-01T12:00:00Z"}
记住要在每行尾部包含一个换行,这样那些使用终端测试API的输出不会被遮挡住。
对于大多数的API友好的响应数据输出总会有更好的表现,你可能受到过不友好打印数据API的影响(例如:非常高的流量占用) 或者是在一些客户端上不能工作 (例如:一个随意编写的程序).
感谢您的阅读,也欢迎您发表关于这篇文章的任何建议,关注我,技术不迷茫!小编到你上高速。
· END ·
最后,关注公众号互联网架构师,在后台回复:2T,可以获取我整理的 Java 系列面试题和答案,非常齐全。
正文结束
推荐阅读 ↓↓↓
1.心态崩了!税前2万4,到手1万4,年终奖扣税方式1月1日起施行~
2.深圳一普通中学老师工资单曝光,秒杀程序员,网友:敢问是哪个学校毕业的?
3.从零开始搭建创业公司后台技术栈
4.程序员一般可以从什么平台接私活?
5.清华大学:2021 元宇宙研究报告!
6.为什么国内 996 干不过国外的 955呢?
7.这封“领导痛批95后下属”的邮件,句句扎心!
8.15张图看懂瞎忙和高效的区别!
HTTP API 设计指南相关推荐
- RESTful API 设计指南[转]
一种软件架构风格.设计风格,而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. RESTful AP ...
- 组件接口(API)设计指南-文件夹
组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
- RESTful API 设计指南
原文地址:http://www.ruanyifeng.com/blog/2014/05/restful_api.html RESTful API 设计指南 作者: 阮一峰 日期: 2014年5月22日 ...
- 服务端指南 | 良好的 API 设计指南
设计一套良好的 API 接口. 原文地址:服务端指南 | 良好的 API 设计指南 博客地址:blog.720ui.com/ 版本号 在 RESTful API 中,API 接口应该尽量兼容之前的版本 ...
- HTTP API 设计指南(基础部分)
为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译 前言 这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Hero ...
- Google API 设计指南 - 前言
原文地址:https://cloud.google.com/apis... Copyright: Creative Commons Attribution 3.0 License Current Ve ...
- google api设计指南-简介
简介 这是联网 API 的通用设计指南.它自 2014 年起在 Google 内部使用,是 Google 在设计 Cloud API 和其他 Google API 时遵循的指南.此设计指南在此处共享, ...
- Google API 设计指南-设计模式
翻译自 API Design Guide - Design Patterns 空响应体 标准的 Delete 方法 必须(must) 返回 google.protobuf.Empty 来实现全局一致性 ...
- Django Api 设计指南
网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备--). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的 ...
最新文章
- Redis概述和基础
- 电机控制应用中的电磁兼容性设计与测试标准
- centos安装JDK与Tomcat
- xshell导出文件用ftp到本地_使用xshell从远程服务器下载文件到本地
- 学会选择最适合自己的GPS定位系统源码
- oracle右连接失效,oracle 右连接
- 下采样downsample代码
- oracle的打开图标,Oracle的SQL Developer 在Ubuntu上以图标显示且双击能运行
- Android:自定义滚动边缘(EdgeEffect)效果
- 2012-09-16-html
- 在PyCharm中自动添加文件头、时间日期等信息
- NOIP 2015复赛提高组Day2 T1==Codevs 4768 跳石头
- awk命令详解+示例
- 弗吉尼亚理工大学计算机科学,弗吉尼亚理工大学计算机科学排名第45(2020年TFE美国排名)...
- 曲线数学NURBS之B样条曲线
- string转map报错
- Python系列-Django-Ninja
- 关于我在刷题时用OJ判题发现的cout相较于printf严重超时的问题
- 【LaTex】利用ins文件和dtx文件生成cls或sty文件,latex宏包的生成与创建方法;配置宏包文件的方法,latex宏包文件放置目录
- IDEO用户体验创新模式01
热门文章
- VirtualBox 虚拟CentOS7新增虚拟盘,并扩充 root和home 目录容量
- iOS底层探索之类的加载(三): attachCategories分析
- 如何利用FL Studio进行听湿录干的声音录制
- 利用Javacsv实现Java读写csv文件
- 安装ECShop报 Non-static method cls_image::gd_version() should not be called statically 解决方案
- 通俗理解数字签名,数字证书和https
- (我总结的实用主义)Loadrunner运行常见错误
- 「leetcode」349. 两个数组的交集:哈希值太大了,还是得用set
- poj 2385 Apple Catching 经典dp
- 在苹果mac中如何使用 Word 画底线、直线、虚线?