设计一个能长期共处的接口

一致性先于漂亮

每条路由用同一套命名规范、同一种响应结构、同一种日期格式、同一种错误结构。十条一致的路由，比五条精妙加五条各不相同的更容易用。

返回稳定的结构：一个带数据和元数据的包装对象，这样加字段时不会破坏调用方。

会回头找你的决定

分页。事先决定——按偏移量还是按游标——并在每个列表里都支持。没有分页的列表总会超出预期地增长。

筛选与排序。要定义好并写进文档，而不是一个让每个调用方自创规则的自由字段。

标识符。稳定、非连续，并且不通过数字泄漏业务信息。

错误是契约的一部分

正确的状态码、一个可以据以分支的固定错误标识、一条可读的消息，以及一个便于排查的请求标识。一个每次错误都返回不同自由文本的接口，会逼着调用方去比对字符串。