如何用AI技术降噪? QCon 广州“音视频架构实践”专场给你答案! 了解详情
写点什么

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

  • 2019 年 11 月 11 日
  • 本文字数:2313 字

    阅读完需:约 8 分钟

设计你的第一个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 已经广为人知了。


  1. REST 与语言无关的。


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


  1. 适当地设计 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



评论资源 API



请注意, 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


2019 年 11 月 11 日 10:492237

评论

发布
暂无评论
发现更多内容

推进智慧城市建设 博睿数据亮相长三角城市数字化转型高峰论坛

博睿数据

数字化转型高峰论坛

为什么我愿意持续做这样一件看似没有价值的事情

leoay

坚持 持续写作 长期价值

Excelize 2.4.0 正式版发布, 新支持 152 项公式函数

xuri

GitHub 开源 Excel Go 语言 Excelize

为什么微服务一定要有 API 网关?

xcbeyond

微服务 api 网关 4月日更

深入理解Java虚拟机-HotSpot

华章IT

Java JVM 虚拟机

百度大脑3月新品推荐:EasyDL视频目标追踪全新发布

百度大脑

百度大脑 EasyDL

《采访彩食鲜 CTO 乔新亮:IT 团队从 100 到 10000 的管理心得》(采访提纲)

程序员历小冰

调查采访能力考核

ARTS- Week 7

steve_lee

对话声网 Agora 首席科学家钟声 :5G时代到来前景下RTE实时互动技术的应用与发展

麦洛

Java

一种提升流媒体服务DSS的IO并发性能方案

Changing Lin

签约计划 4月日更

融合趋势下基于 Flink Kylin Hudi 湖仓一体的大数据生态体系

Apache Flink

flink

Python 爬虫实战(一) 爬取自如网租房信息

U+2647

python 爬虫 4月日更

访谈阿里巴巴安全科学家吴翰清

容光

专访 阿里吴翰清 最新网络安全

浅谈在探索数分之路上的“数据思维”论述

小飞象@木木自由

数据分析 数据分析体系 数据思维 数据分析方法论

奇绩创坛2021秋季创业营开始报名

奇绩创坛

面试4轮字节Java研发岗,最终拿下Offer(原题复盘)

码农之家

编程 程序员 互联网 面试 字节

精通比特币:为什么它对自由、财务和未来至关重要(上篇)

CECBC

比特币

对话声网 Agora 首席科学家钟声 :声网的未来规划和人才建议

小诚信驿站

采访 调查采访能力考核

python 变量作用域和列表

若尘

变量 Python编程 作用域

翻译:《实用的Python编程》09_03_Distribution

codists

Python

【AI全栈二】视频流多目标多类别无延迟高精度高召回目标追踪

cv君

音视频 目标检测 视频跟踪 引航计划

【提纲】专访融云CTO杨攀 | 技术型人才的自我修炼

Python研究所

调查采访能力考核

朱嘉明:算力产业正面临着一个十年的长周期

CECBC

数字经济

浅谈JVM和垃圾回收

SH的全栈笔记

Java JVM JVM虚拟机原理 垃圾回收算法

使用Agora SDK开发React Native视频通话App

声网

RTC React Native 声网 RTE

斗智亦斗棋,零售云市场的“楚河汉界”突围赛

脑极体

架构实战营 模块2 课后作业

༺NPE༻

关于数字人民币、加密货币,央行前行长周小川、副行长李波博鳌论坛发声

CECBC

数字货币

如何从零开始学Python:(3)划重点:使用IDLE创建列表时需要注意的地方

广之巅

Python 4月日更

简单了解InnoDB底层原理

SH的全栈笔记

MySQL 数据库 innodb

Lombok初始使用及遇到的问题

六维

lombok 4月日更

「云智公开课」百度沧海·存储

「云智公开课」百度沧海·存储

设计你的第一个REST API:第一部分_编程语言_Vihanga Liyanage_InfoQ精选文章