股票场内基金交易，没时间盯盘？
原文地址：https://codeplanet.io/principles-good-restful-api-design/
更新：这篇文章已经扩展，出版成书。
前言
好的 API 设计是困难的，API 表示了你的数据和使用这些数据的人的约定，打破这份约定会导致很多愤怒的电子邮件，因为使用这些 API 的人的应用将不能正常工作。API 文档是成功的一半，但是很难找到喜欢写文档的程序员。
要提升服务的质量，构建一个 API 是最终要的事情。通过一个 API ，你的服务有潜力成为一个服务平台。看看现在的这些大科技公司：Facebook, Twitter, Google, GitHub, Amazon, Netflix……如果他们没有通过 API 开放自己的数据，也不可能拥有现在的规模。事实上，整个行业存在的唯一目的就是让大家使用自己平台提供的数据。
“你的 API 越容易，越有更多的人去使用它”
如果你遵守本文档中设计 API 的原则，API 使用者会更加容易的理解使用你的 API。并且减少你收到疑问或批评的邮件机会。我将本文的内容归结成了不同的主题，你不必按照顺序去阅读，可以只看自己需要的部分。
定义
下面是一些本文中要使用的名词，请务必查看：
- 资源：一个对象的单独实例，如一只动物
- 集合：一群同种对象，如动物
- HTTP：一种网络的通信协议
- 客户端：可以创建HTTP请求的客户端应用程序
- 第三方开发者：将使用你的数据的开发者。
- 服务器：一个HTTP服务器或者应用程序，客户端可以跨网络访问它
- 端点：这个API在服务器上的URL用于表达一个资源或者一个集合
- Idempotent: Side-effect free, can happen multiple times without penalty.
- URL段：在URL里面用斜杠分隔的内容
数据设计与抽象
设计 API 比你想象的开始设计时间要更早些。首先，你要确定在怎么设计你的数据，你的服务或应用要如何工作。如果你在一个新项目中开发 API 会比较容易，但是如果你是往现有的项目中添加 API ，你可能需要提供更多的抽象。
有些时候，一个集合可以视为是数据库中的一张表，而一个资源则是这张表中的一行。然而，这只是偶尔的情况。事实上，你的 API 应该尽可能对数据和业务逻辑进行抽象，对于使用你的 API 的第三方开发者，这点很重要。
还有一部分服务是不应该通过 API 暴漏给第三方开发者，一个常见的例子是，很多的 API 都不允许第三方开发者创建用户。
HTTP 动词
你肯定知道 GET 和 POST 请求，这两个是最常见的请求当你使用浏览器访问网页时。POST 这个词，是如此的流行，以至于即使是哪些非互联网工作者也能 POST 数据到 Facebook 上。
这里有你需要了解的四个半 HTTP 动词。我之所以说是四个半，因为 PATCH 和 PUT 非常像，它们两个通常都被开发者合二为一的使用在同一个 API 中。（在这里我假设很多用户都了解数据库增删查改的相关知识）
- GET (选择)：从服务器上获取一个具体的资源或者一个资源列表。
- POST （创建）： 在服务器上创建一个新的资源。
- PUT （更新）：以整体的方式更新服务器上的一个资源。
- PATCH （更新）：只更新服务器上一个资源的一个属性。
- DELETE （删除）：删除服务器上的一个资源。
这里还有两个不太知名的 HTTP 动词：
- HEAD ： 获取一个资源的元数据，如数据的哈希值或最后的更新时间。
- OPTIONS：获取客户端能对资源做什么操作的信息。
良好的 RESTful 风格的 API 允许第三方使用这四个半的动词与数据进行交互，并且这些动词不能出现在 URL 段中。
通常，GET请求可以被浏览器缓存（通常是这样的）。例如，浏览器会缓存 GET 请求（根据头部缓存），并且会在用户进行第二次请求时进行提示。HEAD 请求是基于没有 body 部分的 GET 请求，所以也可以被缓存。
版本控制
无论你在构建什么，无论你在这之前做了多少的计划，你的核心应用总是会发生变化，你的数据关系也会变化，你可能会添加或删除一个属性到你的资源中。这总是会发生在你的开发工作中，只要你的项目还在运行，你的 API 还在被很多人使用。
请记住 API 是服务和客户之间的联系。如果你要改变你的服务器 API，这将会破坏兼容性问题。如果你更改服务器 API 并且这些变化打破了向后兼容性，使用 API 的人员将会讨厌你，甚至会放弃使用你的 API。为了确保你的应用程序的发展，并维持以前的 API 使用者，你需要偶尔的介绍新版本的 API，同时仍然允许访问旧版本。
备注：如果你只是简单地向 API 中添加新功能，例如新的属性，或者只是添加一个新的端点，你不需要增加你的 API 版本号，因为这些改变并不会打破向后兼容性，你只需要更新你的 API 文档即可。
随着时间的退役，你可以声明不赞成旧版本的 API。声明不赞成并不意味着停掉或者降低质量，而是要告诉使用者旧版本的 API 将会在特定的日期删除，他们应该升级到新的版本。
一个好的 RESTful API 会在 URL 中包含版本信息。另一种常见的方式将版本信息放到请求头之中。但是和很多不同的第三方开发者一起工作之后，我可以明确的告诉你，在请求头里面包含版本信息远没有放在 URL 中来得容易。
API 分析
保持跟踪你的 API 被使用的版本或端点。这可以简单的在每次请求 API 时都往数据库中增加一个证书。为什么要跟踪分析 API，有很多理由，例如，你那些最经常被使用的 API 的性能应该被优化的更好。
为了让第三方更好的使用你的 api ，最重要的事情，当你决定不再支持某个 api 的时候，你可以联系开发人员。这是很好的方法在你弃用旧的 api 之前提醒第三方开发者进行升级。
通知第三方开发者的过程可以自动化，比如，当一个即将被弃用的api 被使用 10000 次的时候给开发者发邮件通知。
API Root URL
未完待续。
想获得去掉 5 元限制的证券账户吗？
如果您想去掉最低交易佣金 5 元限制，使用微信扫描左边小程序二维码，访问微信小程序「优财助手」，点击底部菜单「福利」，阅读文章「通过优财开证券账户无最低交易佣金 5 元限制」，按照文章步骤操作即可获得免 5 元证券账户，股票基金交易手续费率万 2.5。
请注意，一定要按照文章描述严格操作，如错误开户是无法获得免 5 元证券账户的。