开发工作中，我们有时需要提供API接口给客户端或者第三方使用，那么如何构建一个能让使用者快速理解的API是一项重要的工作。如何我们在设计API时就严格遵守一些规范，那么在后面的开发过程中沟通成本和效率就会大大改善，我们今天来说说RESETful API的设计规范。
RESTful API 设计的定义
以下是我将贯穿在整个文档中的几个重要的术语：
资源：一个对象的单个实例。比如，一个动物。
集合：一个同类型对象的集合。比如，动物们。
HTTP：网络通信协议。
消费者：能够发生 HTTP 请求的客户端应用程序。
第三方开发者： 不属于你项目组成员但是希望使用你数据的开发者。
服务：一个 HTTP 服务/应用能够通过网络被消费者访问。
节点：服务器上的 API URL ，它能代表资源或整个集合。
幂等性：无副作用，可以多次发生而没有副作用。
URL 段：URL 中由斜杠(“/”)分隔的信息段。
数据抽象与设计
我们需要确定数据库设计以及提供的web服务功能，有了功能设计，我们就可以很好的进行API设计，API应该尽可能抽象业务逻辑和数据，让使用者轻松上手。
请求方法
显然你肯定知道 GET 和 POST 请求，这是最常见的两种请求。POST 如此受欢迎以至于它融入进了其他常见的语言，那些不知道互联网如何运作的人也清楚他们可以在朋友圈『post』一些内容。
这里有四个半非常重要的 HTTP 动词需要你去了解，我说 “半个”，是因为 PATCH 请求和 PUT 请求非常接近。这两个经常被开发人员结合在一起使用。
GET (SELECT)：从服务器或者资源列表中检索特定的资源。
POST (CREATE): 在服务器上创建新的资源。
PUT (UPDATE)：更新服务器上的资源，提供整个资源。
PATCH (UPDATE): 更新服务器上的资源，仅提供改动的属性。
DELETE (DELETE): 从服务器上移除一个资源。
下面是两个不常见的 HTTP 请求方法:
HEAD -- 检索资源的元数据，比如数据的 Hash 值或者最后一次更新的时间。
OPTIONS -- 检索消费者可以对资源进行的操作信息。
一个好的 RESTful API 会利用这四个半 HTTP 请求方法来运行第三方和它提供的数据进行交互，并且绝对不会在 URL 段里包含任何动作。
通常，GET 请求可以被浏览器缓存，例如，浏览器将缓存 GET 请求（ 取决于缓存头 ），如果用户试图发起第二次请求，浏览器将尽可能的提示用户。HEAD 请求基本是一个不带返回主体的 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 之前提醒他们升级的完美方式。
联系及通知第三方开发者过程可以是自动的，例如，例如每当一个过时的特性上发生 10000 次请求时就发邮件通知开发者。
API Root URL
无论你信不信，API 的根地址很重要。当一个开发者接手了一个旧项目。而这个项目正在使用你的 API，同时开发者还想构建一个新的功能，但他们可能完全不知道你提供的哪些服务。幸运的是他们知道客户端对外调用的那些 URL 列表。让你的 API 根入口点保持尽可能的简单是很重要的，因为一个漫长的复杂 URL 设计将令人望而生畏，并且可能会让开发者无法接受。
这里有两个常见的 URL 根例子：
https://example.org/api/v1/*https://api.example.com/v1/*
如果你的应用很庞大或者你预期它将会变的很庞大，那么将 API 放到子域下（如 api.example.com）通常是一个好选择。这种做法可以保持某些规模化上的灵活性。
但如果你觉得你的 API 不会变的很庞大，或是你只是想让应用安装更简单些（如你想用相同的框架来支持站点和 API），将你的 API 放到根域名下（如 example.com/api）也是可以的。
让 API 根拥有一些内容通常也是个好主意。Github 的 API 根就是一个典型的例子。从个人角度来说我是一个通过根 URL 发布信息的粉丝，这对很多人来说是有用的，例如如何获取 API 相关的开发文档。
同样也请注意 HTTPS 前缀，一个好的 RESTful API 总是基于HTTPS 来发布的。
端点
一个端点就是指向特定资源或资源集合的 URL。
如你正在构建一个虚构的 API 来展现几个不同的动物园，每一个动物园又包含很多动物，员工和每个动物的物种，你可能会有如下的端点信息：
https://api.example.com/v1/**zoos**
https://api.example.com/v1/**animals**
https://api.example.com/v1/**animal_types*...
https://api.example.com/v1/**employees**
针对每一个端点来说，您需要列出有效的 HTTP 动词和端点组合。以下是我们的虚构 API 可以执行的半全面（semi-comprehensive）的操作列表。请注意我把 HTTP 动词都放在了虚构的 API 之前，正如将同样的注解放在每一个 HTTP 请求头里一样。
GET /zoos: 列出所有动物园 (ID、NAME等信息不要太详细)
POST /zoos: 创建一个新的动物园
GET /zoos/ZID: 获取一个动物园详情
PUT /zoos/ZID: 更新指定动物园
PATCH /zoos/ZID: 更新指定动物园（局部数据）
DELETE /zoos/ZID: 删除指定动物园
GET /zoos/ZID/animals: 检索指定动物园下动物列表（ID、NAME 不要太详细）
GET /animals: 列出所有动物（ID、NAME 不要太详细）
POST /animals: 创建一个新的动物
GET /animals/AID: 获取指定动物详情
PUT /animals/AID: 更新指定动物
PATCH /animals/AID: 更新指定动物（局部数据）
GET /animal_types: 检索动物类型列表（ID、NAME 不要太详细）
GET /animal_types/ATID: 检索指定的动物类型
GET /employees: 获取雇员列表（ID、NAME 不要太详细）
GET /employees/EID: 获取指定雇员详情
GET /zoos/ZID/employees: 获取指定动物园下的雇员列表
POST /employees: 创建一个新的雇员
POST /zoos/ZID/employees: 为指定动物园聘请一个雇员
DELETE /zoos/ZID/employees/EID: 删除指定动物园下的指定雇员
在上面的列表里，ZID 表示动物园的 ID， AID 表示动物的 ID，EID 表示雇员的 ID，还有 ATID 表示物种的 ID。让文档里所有的东西都有一个关键字是一个好主意。
为简洁起见，我在上面的示例中省略了公共 API URL前缀。作为沟通方式这没什么问题，但是如果你真要写到API文档中，那就必须包含完整的路径（如，GET http://api.example.com/v1/animal_type/ATID）。
请注意如何展示数据之间的关系，特别是雇员与动物园之间