在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
开源软件名称:cocoajin/http-api-design-ZH_CN开源软件地址:https://github.com/cocoajin/http-api-design-ZH_CN开源编程语言:HTML 100.0%开源软件介绍:HTTP API 设计指南
前言这篇指南介绍了大量的 http + json 的api设计风格,最初摘录自heroku平台的api设计指引 Heroku 平台 API 指引. 这篇指南除了当前那些API,同时也适用于heroku平台新集成的api,我们希望那些在heroku之外的api设计者也感兴趣! 我们的目标是一致性,专注业务逻辑同时避免设计上的空想,我们一直在寻找一种良好的,统一的,显而易见的API设计方式,未必只有一种方式。 我们假设你熟悉基本的 http+json api 设计方式,但是,不一定包含在此篇指南里面的所有内容。 内容
返回合适的状态码为每一次的响应返回合适的HTTP状态码. 成功的HTTP响应应该使用如下的状态码:
对于用户请求的错误情况,及服务器的异常错误情况,请查阅完整的HTTP状态码HTTP response code spec。 提供全部可用的资源提供全部可显现的资源 (例如. 这个对象的所有属性) 不用考虑全部可能响应的状态码,总是在响应码为200或是201时返回所有可用资源, 包含
当请求状态码为202时,不返回所有可用资源, e.g.:
在请求的body体使用JSON数据在
提供资源的唯一标识在默认情况给每一个资源一个 返回的唯一标识要用小写字母并加个分割线格式
提供标准的时间戳提供默认的资源创建时间,更新时间 {
...
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T13:00:00Z",
...
} 这些时间戳可能不适用于某些资源,这种情况下可以忽略省去。 使用ISO8601的国际化时间格式在接收的返回时间数据时只使用UTC格式. 查阅ISO8601时间格式, 例如:
使用统一的资源路径资源命名使用复数形式为资源命名,而不是在系统中有争议的一个单个资源 (例如,在大多数系统中,给定的用户帐户只有一个). 这种方式保持了特定资源的统一性. 形为好的末尾展现形式不许要指定特殊的资源形为,在某些情况下,指定特殊的资源的形为是必须的,用一个标准的
例如.
路径和属性要用小写字母使用小写字母并用
同样属性也要用小写字母, 但是属性名字要用下划线
嵌套外键关系序列化的外键关系通常建立在一个有嵌套关系的对象之上, 例如.: {
"name": "service-production",
"owner": {
"id": "5d8201b0..."
},
...
} 而不是这样 例如: {
"name": "service-production",
"owner_id": "5d8201b0...",
...
} 这种方式尽可能的把相关联的资源信息内联在一起,而不用改变响应资源的结构,或者展示更高一级的响应区域, 例如: {
"name": "service-production",
"owner": {
"id": "5d8201b0...",
"name": "Alice",
"email": "[email protected]"
},
...
} 支持方便的无id间接引用在某些情况下,为了方便用户使用接口,在末尾提供用id标识资源,例如,一个用户想到了他在heroku平台app的名字,但是这个app的唯一标识是id,这种情况下,你想让接口通过名字和id都能访问,例如:
不要只接受使用名字而剔除了使用id。 构建错误信息在网络请求响应错误的时候,返回统一的,结构化的错误信息。要包含一个机器可读的错误
{
"id": "rate_limit",
"message": "Account reached its API rate limit.",
"url": "https://docs.service.com/rate-limits"
} 把你的错误信息格式文档化,以及这些可能的错误信息 支持Etags缓存在所有请求响应中包含一个 用id来跟踪每次的请求在每一个API响应中要包含一个 按范围分页对于服务器响应的大量数据我们应该为此分页。
使用 显示速度限制状态客户端的访问速度限制可以维护服务器的良好状态,进而为其他客户端请求提供高性的服务.你可以使用token bucket algorithm技术量化请求限制. 为每一个带有 指定可接受头信息的版本在开始的时候指定API版本,使用
最好不要给出一个默认的版本, 而是要求客户端明确指明他们要使用特定的版本. 减少路径嵌套在一些有父路径/子路径嵌套关系的资源数据模块中, 路径可能有非常深的嵌套关系, 例如:
推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源,例如在下面的情况下,dyno属性app范围下,app属性org范围下:
提供机器可读的JSON概要提供一个机器可读的概要恰当的表现你的API.使用
prmd管理你的概要, 并且确保用 提供人类可读的文档提供人类可读的文档让客户端开发人员可以理解你的API。 如果你用prmd创建了一个概要并且按上述要求描述,你可以很容易的生成所有结节使用 除此之在详细信息的结尾,提供一个关于如下信息的API摘要:
提供可执行的示例提供可执行的示例让用户可以直接在终端里面看到API的调用情况,最大程度的让这些示例可以逐字的使用,以减少用户尝试使用API的工作量。例如:
如果你使用prmd生成Markdown文档, 你会自动获取一些示例在结点处。 描述稳定性描述您的API的稳定性或是它在各种各样节点环境中的完备性和稳定性 例如. 带有 原型/开发版/产品 等标签. 更多关于可能的稳定性和改变管理的方式,查看 Heroku API compatibility policy 一旦你的API宣布产品正式版本及稳定版本时, 不要在当前API版本回退做一些不兼容的改变。如果你需要回退做一些不兼容的改变,请创建一个新的版本的API。 要求传输通道安全要求在传输通道安全的情况下访问API,这点没什么可解释的了. 因为这不值得去争辩在什么时候使用传输通道安全访问API是好的,什么时候是不好的,只需要记住在访问API时,使用安全传输通道就行了。 使用友好的JSON输出用户在第一次看到你的API使用情况,很可能是在命令行下使用 {
"beta": false,
"email": "[email protected]",
"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":"[email protected]","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的影响(例如:非常高的流量占用) 或者是在一些客户端上不能工作 (例如:一个随意编写的程序). 译者注
|
2023-10-27
2022-08-15
2022-08-17
2022-09-23
2022-08-13
请发表评论