HTTP API 设计指南(响应部分)
为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译
前言
这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Heroku 平台的 API 设计指引 Heroku 平台 API 指引。
这篇指南除了详细介绍现有的 API 外,Heroku 将来新加入的内部 API 也会符合这种设计模式,我们希望非 Heroku 员工的API设计者也能感兴趣。
我们的目标是保持一致性,专注业务逻辑同时避免过度设计。我们一直试图找出一种良好的、一致的、显而易见的 API 设计方法,而并不是所谓的"最终/理想模式"。
我们假设你熟悉基本的 HTTP+JSON API 设计方法,所以本篇指南并不包含所有的 API 设计基础。
我们欢迎你为这篇指南做贡献。
提供资源的(UU)ID
在默认情况给每一个资源一个id
属性。除非有更好的理由,否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识,尤其是自动增长的id。
生成小写的UUID格式 8-4-4-4-12
,例如:
"id": "01234567-89ab-cdef-0123-456789abcdef"
提供标准的时间戳
为资源提供默认的创建时间 created_at
和更新时间 updated_at
,例如:
{..."created_at": "2012-01-01T12:00:00Z","updated_at": "2012-01-01T13:00:00Z",...
}
有些资源不需要使用时间戳那么就忽略这两个字段。
使用UTC(世界标准时间)时间,用ISO8601进行格式化
在接收和返回时都只使用UTC格式。ISO8601格式的数据,例如:
"finished_at": "2012-01-01T12:00:00Z"
嵌套外键关系
使用嵌套对象序列化外键关联,例如:
{"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
,一个人类能识别的错误信息(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
。
显示频率限制状态
客户端的访问速度限制可以维护服务器的良好状态,保证为其他客户端请求提供高性的服务。你可以使用token bucket algorithm技术量化请求限制。
为每一个带有RateLimit-Remaining
响应头的请求,返回预留的请求tokens。
保证响应JSON最小化
请求中多余的空格会增加响应大小,而且现在很多的HTTP客户端都会自己输出可读格式("prettify")的JSON。所以最好保证响应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"
}
你可以提供可选的方式为客户端提供更详细可读的响应,使用查询参数(例如:?pretty=true
)或者通过Accept
头信息参数(例如:Accept: application/vnd.heroku+json; version=3; indent=4;
)
HTTP API 设计指南(响应部分)相关推荐
- 服务端指南 | 良好的 API 设计指南
设计一套良好的 API 接口. 原文地址:服务端指南 | 良好的 API 设计指南 博客地址:blog.720ui.com/ 版本号 在 RESTful API 中,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日 ...
- HTTP API 设计指南(基础部分)
为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译 前言 这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Hero ...
- Google API 设计指南-设计模式
翻译自 API Design Guide - Design Patterns 空响应体 标准的 Delete 方法 必须(must) 返回 google.protobuf.Empty 来实现全局一致性 ...
- 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 时遵循的指南.此设计指南在此处共享, ...
- Django Api 设计指南
网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备--). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的 ...
最新文章
- 被解放的姜戈02 庄园疑云
- 类与类之间 相同属性及字段拷贝
- 带实证明,imshow是能显示数据归一化到0到1的图像的!
- 玩转Mixly – 3、Arduino AVR编程 之 控制
- git rebase -i 汇合提交
- dubbo优势_Dubbo 迈出云原生重要一步 应用级服务发现解析
- java对象的序列化机制详解
- java时间加减_java时间加减
- PowerShell与系统开局(下)
- soapui生成java客户端_用soapUI生成客户端代码
- 工业控制系统基础知识
- Python入门(3)
- October CMS
- 五一国际劳动节知多少!祝五一劳动节快乐! Happy International Workers‘Day!
- 十一、SpringCloud实用篇_Gateway服务网关
- word 如何设置页码?分页?分节?
- vuex本地储存方案
- 详解关于MTK驱动开发学习教程
- Android 淘气三千传之 —— 插件化的一点理解(上)
- ajax异步上传什么意思,使用 jQuery 的 AJAX 异步上传文件
热门文章
- 帆软9.0动态列之解决动态列的分组统计问题
- 使用oracle执行txt语句,oracle常用SQL语句.txt
- linux web目录安全设置,[LNMP]Linux的Web环境的安全配置
- Centos 7 安装 java、搭建 Jenkins
- (一)Maven简介
- 看朋友日志发现的一个ios下block相关的内存管理问题,非常奇怪,请大家帮忙一起来回答!...
- “英伦配”收视牛过本山,网管软件如何配奇兵
- 你所不知道的 CSS 滤镜技巧与细节
- 暗渡陈仓:用低消耗设备进行破解和渗透测试2.3 本章小结
- 回忆一次面试Android研发的问题