欢马劈雪的技术文章、集册、实例源码

时代Java，与您同行！关注微信公众号，关注前沿技术，微信搜索：nowjava或时代Java，也可点击这里扫码关注

时代Java

登录注册

京东自营 + 国补 iPhone 历史最低价国家补贴享8折

欢马劈雪

生成结构化的错误

响应错误的时，生成统一的、结构化的错误信息。包含一个机器可读的错误 id，一个人类能识别的错误信息（message），根据情况可以添加一个url来告诉客户端关于这个错误的更多信息以及如何去解决它，例如:HTTP/1.1 429 Too Many Requests{ "id": "rate_limit", "message": "Account reached its API rate limit.", "url": "https://docs.service.

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

生成，结构化，错误， http， api
嵌套外键关系

使用嵌套对象序列化外键关联，例如:{ "name": "service-production", "owner": { "id": "5d8201b0..." }, // ...}而不是像这样:{ "name": "service-production", "owner_id": "5d8201b0...", ...

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

嵌套，关系， http， api，设计
使用 UTC（世界标准时间）时间，用 ISO8601 进行格式化

在接收和返回时都只使用 UTC 格式。ISO8601 格式的数据，例如:"finished_at": "2012-01-01T12:00:00Z"

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

使用， utc，世界，标准时间，时间
提供标准的时间戳

为资源提供默认的创建时间 created_at 和更新时间 updated_at，例如:{ ... "created_at": "2012-01-01T12:00:00Z", "updated_at": "2012-01-01T13:00:00Z", ...}有些资源不需要使用时间戳那么就忽略这两个字段。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

提供，标准，时间戳， http， api
提供资源的(UU)ID

在默认情况给每一个资源一个id属性。除非有更好的理由，否则请使用 UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识，尤其是自动增长的 id。生成小写的UUID格式 8-4-4-4-12，例如："id": "01234567-89ab-cdef-0123-456789abcdef"

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

提供，资源， uu， id， http
最小化路径嵌套

在一些有父路径/子路径嵌套关系的资源数据模块中，路径可能有非常深的嵌套关系，例如:/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}

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

最小化，路径，嵌套， http， api
支持方便的无 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.

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

支持，方便， id，间接，引用
路径和属性要小写

为了和域名命名规则保持一致，使用小写字母并用-分割路径名字，例如：service-api.com/usersservice-api.com/app-setups属性也使用小写字母，但是属性名要用下划线_分割，以便在Javascript中省略引号。例如：service_class: "first"

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

路径，属性，小写， http， api
使用统一的资源路径格式

资源名称使用复数来命名资源，除非该资源在系统中是单件（比如，在绝大多数系统中，一个用户只能拥有一个账户）。这样在你引用特定资源时可以保持一致性。对独有的资源使用不需要特定动作的 endpoint 格式。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

使用，统一，资源，路径，格式
在请求的 body 体使用 JSON 格式数据

在 PUT/PATCH/POST 请求的正文（request bodies）中使用JSON格式数据，而不是使用 form 表单形式的数据。这与我们使用JSON格式返回请求相对应，例如:$ curl -X POST https://service.

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

请求， body，使用， json，格式
提供全部可用的资源

提供全部可显现的资源 (例如：这个对象的所有属性) ，当响应码为 200 或是 201 时返回所有可用资源，包含 PUT/PATCH 和 DELETE请求，例如:$ curl -X DELETE \ https://service.com/apps/1f9b/domains/0fd4HTTP/1.1 200 OKContent-Type: application/json;charset=utf-8...{ "created_at": "2012-01-01T12:00:00Z", "hostname": "subdomain.example.

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

提供，全部，可用，资源， http
返回合适的状态码

为每一次的响应返回合适的HTTP状态码。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

返回，合适，状态， http， api
通过请求中的范围（Range）拆分大的响应

一个大的响应应该通过多个请求使用Range头信息来拆分，并指定如何取得。详细的请求和响应的头信息（header），状态码(status code)，范围(limit)，排序(ordering)和迭代(iteration)等，参考Heroku Platform API discussion of Ranges。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

通过，请求，范围， range，拆分
为内省而提供 Request-Id

为每一个请求响应包含一个Request-Id字段，并使用 UUID 作为该值。通过在客户端、服务器或任何支持服务上记录该值，它能主我们提供一种机制来跟踪、诊断和调试请求。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

内省，提供， request-id， http， api
支持 Etag 缓存

, identifying the specificversion of the returned resource. The user should be able to check forstaleness in their subsequent requests by supplying the value in theIf-None-Match header.在所有的请求中带上 ETag 头，用于识别特定版本的返回资源。用户可以在随后的请求中通过提供 If-None-Match头的值来检查内容是否过期。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

支持， etag，缓存， http， api
强制头信息 Accept 中提供版本号

制定版本并在版本之间平缓过渡对于设计和维护一套 API 是个巨大的挑战。所以，最好在设计之初就使用一些方法来预防可能会遇到的问题。为了避免 API 的变动导致用户使用中产生意外结果或调用失败，最好强制要求所有访问都需要指定版本号。请避免提供默认版本号，一旦提供，日后想要修改它会相当困难。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

强制，信息， accept，提供，版本号
强制使用安全连接（Secure Connections）

所有的访问 API 行为，都需要用 TLS 通过安全连接来访问。没有必要搞清或解释什么情况需要 TLS 什么情况不需要 TLS，直接强制任何访问都要通过 TLS。理想状态下，通过拒绝所有非 TLS 请求，不响应 http 或 80 端口的请求以避免任何不安全的数据交换。如果现实情况中无法这样做，可以返回 403 Forbidden响应。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

强制，使用，安全，连接， secure
隔离关注点

设计时通过将请求和响应之间的不同部分隔离来让事情变得简单。保持简单的规则让我们能更关注在一些更大的更困难的问题上。请求和响应将解决一个特定的资源或集合。使用路径（path）来表明身份，body 来传输内容（content）还有头信息（header）来传递元数据（metadata）。查询参数同样可以用来传递头信息的内容，但头信息是首选，因为他们更灵活、更能传达不同的信息。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

隔离，关注点， http， api，设计
HTTP API 设计指南

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

欢马劈雪 2020-12-28 13:56:55 2020-08-04 05:37:59

http， api，设计，指南
与屈原对话及开源精神

端午节到了，人们都在讨论屈原不屈不挠的精神，以及龙舟、粽叶等世界文化遗产。粽叶清淡，给人无限的遐想。或者，你很容易想起和粽叶形状比较类似的竹叶，以及屹立挺拔的骨感竹子。竹在清风中瑟瑟的声音，在夜月下疏朗的影子，都让文人墨客深深感动。而竹于风霜凌厉中苍翠依然的品格，更让诗人引为同道。苏东坡曾在《于潜僧绿筠轩》里宣称，“宁可食无肉，不可居无竹。

欢马劈雪 2020-08-04 17:37:59 2020-08-04 05:37:59

屈原，对话，开源，精神，自己

个人简介

欢马劈雪
纵马驰骋迎雪而行
获得 161932 积分
https://nowjava.com/creator/10001

欢马劈雪

生成结构化的错误

嵌套外键关系

使用 UTC（世界标准时间）时间，用 ISO8601 进行格式化

提供标准的时间戳

提供资源的(UU)ID

最小化路径嵌套

支持方便的无 id 间接引用

路径和属性要小写

使用统一的资源路径格式

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

提供全部可用的资源

返回合适的状态码

通过请求中的范围（Range）拆分大的响应

为内省而提供 Request-Id

支持 Etag 缓存

强制头信息 Accept 中提供版本号

强制使用安全连接（Secure Connections）

隔离关注点

HTTP API 设计指南

与屈原对话及开源精神

个人简介

欢马劈雪

纵马驰骋迎雪而行

获得 161932 积分

https://nowjava.com/creator/10001

热门标签

社区

关于