设计你的第一个 REST API：第一部分

本文将介绍使用 Swagger 编写 API 定义所需的 REST API 的最常见的概念。然后，您可以使用自己喜欢的语言将该定义转换为代码。

请注意，您需要了解基本的 HTTP 和 API 相关知识。

您可能会喜欢：获取大量REST：REST API 教程

REST 是什么？

REST 是 REpresentational State Transfer（表述性状态转移）的缩写。它是一种设计 API 的架构风格；它提供了一组可以简化系统间通信的标准。

REST 是由计算机科学家 Roy Fielding 定义的。他在 2000 年的博士论文中提出了 REST 的原则。

使用 REST 有很多优点，它使得这种架构风格成为 API 的 Internet 标准。

1. 基于 REST 的交互是使用 HTTP 实现的。

• 这使得任何人在没有学习曲线的情况下，都可以轻松地使用 REST ，因为 HTTP 已经广为人知了。

2. REST 与语言无关的。

• 我们可以使用我们喜欢的任何语言来实现 REST API，事实上，有很多工具可以在定义 API 时自动生成代码框架。

3. 适当地设计 REST API 是不言而喻的。

• REST 概念被设计成在 API 中具有这种行为。当我们看到一个适当设计的 REST API 时，我们可以在不阅读文档的情况下理解每个资源路径的功能。

REST 的概念

为了进一步使用 REST API，我们需要先理解一些概念。

资源

资源是我们需要使用 REST API 来修改的数据对象。这些资源对象通常包含类型、关联数据、与其他资源的关系以及一组对其进行操作的方法。它类似于面向对象编程语言中的对象实例，不同之处在于它只定义了几个标准方法。

路径

REST API 中的每个资源都会定义一个路径，通过该路径可以对该资源进行操作。在大多数情况下，它是 API 基本路径和资源名的连接。

请求/响应头

发送到服务端并返回用于指定请求/响应类型、编码、内容类型、自定义参数等额外信息。

响应编码

这些编码随响应一起返回，它表示发送到服务端的请求的状态，使用的是标准的 HTTP 响应编码。

REST 操作

REST API 是使用 HTTP 的标准操作来定义的。

GET 返回响应，POST 创建资源，PUT 更新资源，DELETE 删除资源。

REST 原则

无状态

• 无状态意味着服务端不需要记住使用 API 的用户的任何信息。每个单独的请求都包含了服务端执行请求和返回响应所需的所有信息，而不用考虑同一个 API 用户发出的其他请求。

• 而且，响应还应该包含足够的信息，以便客户端可以理解发送的数据。

统一接口

• 服务端中的每个资源都应该只有一个逻辑 URI ，并且应该公开访问该资源的方法。

• API 中的路径应该遵循标准的命名约定。

• 所有资源都应该使用通用方法来访问，这可以增强 Web 接口的可见性。

客户端－服务端分离

• 客户端和服务端的实现应该是独立的。

• 两者都应该能够独立地扩展和演进。

• 客户端应该只知道服务端上资源的 URI，而不知道其他内容。

• 服务端应根据从客户端收到的请求返回适当的响应。

分层系统

• Web 服务应该遵循分层的方法论，也就是说，我们应该将 Web 服务划分为不同的层，这些层只能看到它们最接近的层，比如认证层、数据访问层、消息处理器层等。

• 尽管如此，这些层不应该影响请求或响应。客户端不应该知道它和响应请求的实际服务端之间到底有多少层（如果有的话）。

可缓存

• 服务端应在响应中发送关于数据是否可缓存的信息。如果数据是可缓存的，那么它可能会包含某种版本号。

一个 API 示例

让我们看看如何定义一个我们自己的简单的 REST API。为了更方便地理解 REST 的概念，我考虑使用一个简单的在线书店的场景。我们需要使用新的 REST API 暴露主要资源 books。书籍对象有几个属性，如唯一 id、名称、作者和价格，并且一本书还可以有多条评论。

{    "id": "B10001",    "name": "The Adventures of Tom Sawyer",    "author": "Mark Twain",    "price": "$4.90",    "reviews": [        {              "id": "R1001234",            "score": 4.3,            "comment": "Good book to read.",            "user": "vihanga"        }        ...    ]}

因此，我们可以将评论看作是 API 的另一种资源，它存在于图书资源内部。

现在，让我们看下可以定义哪些 API 来使用这两种资源吧。

图书资源 API

• GET https://mybookstore.com/api/books/
  

• 返回所有书籍对象

• POST https://mybookstore.com/api/books/
  

• 在系统中创建一本新书

• PUT https://mybookstore.com/api/books/{book-id}

• 替换由 book-id 标识的书籍对象的内容

• DELETE https://mybookstore.com/api/books/{book-id}

• 删除由 book-id 标识的书籍对象。

评论资源 API

• GET https://mybookstore.com/api/books/{book-id}/reviews

• 返回由 book-id 标识的书籍对象的所有评论。

• POST https://mybookstore.com/api/books/{book-id}/reviews

• 为 book-id 标识的书籍对象创建一条评论

• PUT https://mybookstore.com/api/books/{book-id}/reviews/{review-id}

• 替换由 book-id 标识的书籍对象中由 review-id 标识的评论的内容

• DELETE https://mybookstore.com/api/books/{book-id}/reviews/{review-id}

• 删除由 book-id 标识的书籍对象中由 review-id 标识的评论

请注意， reviews 资源的所有路径都是在由 book-id 标识的特定的图书资源下定义的。这是因为根据我们的业务用例，没有书籍就没有书评。

现在我们已经知道怎样创建 REST API 的基本框架了，那么我们可以开始定义每个路径的更细粒度的细节了，比如定义应该如何发送请求体、返回什么类型的响应对象、可能发送什么错误码等等。为此，我们可以使用许多互联网上免费提供的工具，我本人更喜欢使用 SwaggerHub。我们可以免费创建一个帐户。

我将在下一篇文章中详细解释这些信息。

希望您对 REST 的基本知识已经有所了解了，如果您有任何问题，请发表评论。

敬请期待下篇文章！

进一步阅读

REST API: Your Guide to Getting Started Quickly

Foundations of RESTful Architecture

原文链接：

Designing Your First REST API – Part 1