在项目中往往会需要确定一个好的API风格，到底有哪些风格可以参考，API Style 的细节要点有哪些呢？
Http API Style 有哪些？
- SOAP：tend to be centered around operations that are usually use-case specific and specialized.
- REST：centered around business (data) entities exposed as resources that are identified via URIs and can be manipulated via standardized CRUD-like methods using different representations, and hypermedia
- GraphQL：a query language for APIs and a runtime for fulfilling those queries with your existing data
SOAP 风格（严格来说，算不上风格）最早于1998年由微软提出；REST 风格于2000年 由 Roy Thomas Fielding 论文中提出；GraphQL 于2015年由 Facebook 提出；
- SOAP vs REST
如果要轻松、快速地完成API设计，SOAP 风格的API就足够了。毕竟REST有时很难做到，尤其是在一开始。但随着时间的推移，使用RESET 风格的API，服务器端的演进变得更容易，客户机对变化的适应能力也更强。
- REST vs GraphQL
REST 限于其历史背景，对于
查询操作一些细节并没有太多描述，随着互联网的发展，查询的复杂度越来越高，而 GraphQL 是一个很好的补充。
在业界有将近70%的API是REST-like的风格，其中当然就包括谷歌、微软等行业巨头，REST 差不多已经成为了事实上的标准，了解、用好 REST 十分必要。
REST 是什么？
REST，全称是 Resource Representational State Transfer：通俗来讲就是：资源在网络中以某种表现形式进行状态转移。分解开来：
- Resource：资源，即数据（前面说过网络的核心）。比如 newsfeed，friends等；
- Representational：某种表现形式，比如用JSON，XML，JPEG等；
- State Transfer：状态变化。通过HTTP动词实现。
资源模型
资源是具有类型、数据、与其他资源关系、以及一组对其进行操作的方法的对象。
Richardson成熟度模型
Level 0
不使用任何URI，HTTP方法和HATEOAS功能。
该模型的出发点是使用HTTP作为远程交互的传输系统，但不使用Web的任何机制。基本上就是使用HTTP作为你远程交互机中的隧道机制，通常基于“远程过程调用“（RPC，Remote Procedure Invocation ）。
Level 1 - Resources
使用 URI、HTTP方法、HATEOAS中的URI。
迈向REST的第一步就是引入资源的概念。接下来，我们所要讨论的是各个资源，而不是将所有请求发送到单一的服务端点。每个资源都由唯一的URI单独标识
Level 2 - HTTP Verbs
使用 URI、HTTP方法、HATEOAS中的URI和HTTP。
支持每个公开资源上的几个HTTP谓词 - 创建，读取，更新和删除（CRUD）服务。通常代表业务实体的资源状态可以通过网络进行操作。
Level 3 - Hypermedia Controls
使用所有三个，即URI，HTTP和HATEOAS。
超媒体控制的关键在于它告诉我们下一步我们可以做什么，以及操作所需资源的URI。与我们必须提前知道在哪里创建预约请求不同（Level2中），在响应中的 HATEOAS 告诉了我们下一步该如何做，以完成应用程序状态转换。
关键问题
REST 本身不是标准，只是一种风格。因此只要遵从该风格，都是OK的。然而，除此之外我们逃不开使用中遇到的很多问题，最典型的问题，如下：
- Error Handling
- Sorting
- Pagination
- versioning
- filtering
- Long running
- Sub-collection
- Action(i.e. Batch Operation)
Error handling
详见：跨服务错误处理
Sorting
如果 API 方法允许客户端指定列表结果的排序顺序，则请求消息应该包含一个字段：
string order_by = ...;
说明：语法中的冗余空格字符是无关紧要的。
"foo,bar desc"和" foo , bar desc "是等效的。
字符串值应该遵循 SQL 语法：逗号分隔的字段列表。例如："foo,bar"。默认排序顺序为升序。要将字段指定为降序，应该将后缀 " desc" 附加到字段名称中。例如："foo desc,bar"。
Pagination
- 可列表集合应该支持分页，即使结果通常很小。
说明：如果某个 API 从一开始就不支持分页，稍后再支持它就比较麻烦，因为添加分页会破坏 API 的行为。 不知道 API 正在使用分页的客户端可能会错误地认为他们收到了完整的结果，而实际上只收到了第一页。
- 翻页方式
| 后台存储 | Request | Response |
| 搜索引擎 | { “page_num”: 1, // 页码从 1 开始 “page_size”: 10 } |
{ “code”: 0, “msg”: “”, “data”: { “total_cnt”: 100, “items”: [] } } |
| 数据库 | { “last_id”: 1, // 第一页，默认传0 “page_size”: 10 } |
{ “code”: 0, “msg”: “”, “data”: { “items”: [], “next_id”: 10 // 下一页放到last_id的值 } } |
Versioning
业界方案
- 无版本控制
这是最简单的方法，它对于一些内部 API 来说可能是可以接受的。 重大变化可以表示为新资源或新链接。 向现有资源添加内容可能不会带来重大更改，因为不希望看到此内容的客户端应用程序将忽略它。
https://adventure-works.com/customers/3
- URI 版本控制
每次修改 Web API 或更改资源的架构时，向每个资源的 URI 添加版本号。 以前存在的 URI 应像以前一样继续运行，并返回符合原始架构的资源。
https://adventure-works.com/v2/customers/3
- 查询字符串版本控制
不是提供多个 URI，而是可以通过在追加到 HTTP 请求后面的查询字符串中使用参数来指定资源的版本，例如
https://adventure-works.com/customers/3?version=2
注意：某些较旧的 Web 浏览器和 Web 代理不会缓存在 URI 中包含查询字符串的请求的响应。 这可能会降低使用 Web API 并在此类 Web 浏览器中运行的 Web 应用程序的性能。
