restful-api-design-references

关于「能愿动词」的使用 为了避免歧义，文档大量使用了「能愿动词」，对应的解释如下： 必须 (MUST) ：绝对，严格遵循，请照做，无条件遵守； 一定不可 (MUST NOT) ：禁令，严令禁止； 应该 (SHOULD) ：强烈建议这样做，但是不强求； 不该 (SHOULD NOT) ：强烈不建议这样做，但是不强求； 可以 (MAY) 和 可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少； 参见：RFC 2119 Protocol 客户端在通过 API 与后端服务通信的过程中， 应该 使用 HTTPS 协议。 API Root URL API 的根入口点应尽可能保持足够简单，这里有两个常见的 URL 根例子： api.example.com/* example.com/api/* 如果你的应用很庞大或者你预计它将会变的很庞大，那 应该 将 API 放到子域下（ api.example.com ）。这种做法可以保持某些规模化上的灵活性。 Versioning 所有的 API 必须保持向后兼容，你 必须 在引入新版本 API 的同时确保旧版本 API 仍然可用。所以 应该 为其提供版本支持。 目前比较常见的两种版本号形式： 在 URL 中嵌入版本编号 api.example.com/v1/* 这种做法是版本号直观、易于调试；另一种做法是，将版本号放在 HTTP

Resetful API 设计规范 本文是为 大渝网 API 开发规范拟定的一个 beta 版，文章大量参考了目前比较常见的 RESETful API 设计。 为了更好的讨论规范带来的争议及问题，现已把该文档整理并开源到 github ，关于大家补充及提问。 关于「能愿动词」的使用 为了避免歧义，文档大量使用了「能愿动词」，对应的解释如下： 必须 (MUST) ：绝对，严格遵循，请照做，无条件遵守； 一定不可 (MUST NOT) ：禁令，严令禁止； 应该 (SHOULD) ：强烈建议这样做，但是不强求； 不该 (SHOULD NOT) ：强烈不建议这样做，但是不强求； 可以 (MAY) 和 可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少； 参见： RFC 2119 Protocol 客户端在通过 API 与后端服务通信的过程中， 应该 使用 HTTPS 协议。 API Root URL API 的根入口点应尽可能保持足够简单，这里有两个常见的 URL 根例子： api.example.com/* example.com/api/* 如果你的应用很庞大或者你预计它将会变的很庞大，那 应该 将 API 放到子域下（ api.example.com ）。这种做法可以保持某些规模化上的灵活性。 Versioning 所有的 API 必须保持向后兼容，你 必须