restful api设计_RESTful API设计

最新推荐文章于 2024-07-20 20:24:10 发布

cunfen8879

最新推荐文章于 2024-07-20 20:24:10 发布

阅读量161

点赞数

文章标签： python java 数据库大数据 linux

原文链接：https://www.javacodegeeks.com/2020/08/restful-api-design.html

版权

restful api设计

在编写API规范之前，必须考虑RESTful API规范的五个主要方面。

在本文中，我将使用产品用例的示例来讨论这五个功能。在开始之前，请确保我们了解API和REST的含义。

如果您已经熟悉API设计并且想进一步学习，建议您看一下该教程：如何使用API Designer设计RESTful API 。

什么是API？

应用程序编程接口(API)是一组规则，用于定义软件组件如何与另一个软件组件进行交互。在Web服务的上下文中，这些交互关系与根据持久性存储的四个基本功能(创建，读取，更新和删除(CRUD))进行数据的操纵和检索有关。定义这些规则的样式称为“ REST建筑样式”。这是由Roy Fielding博士在其2000博士论文“体系结构样式和基于网络的软件体系结构设计”中设计的。

什么是REST？

REST代表代表性状态转移。它提供了一种表示资源(即数据)并通过调用URI通过HTTP传输资源的方法。 URI将数据表示为名词，而数据功能(CRUD)由HTTP方法表示。通常，HTTP方法将映射到CRUD功能，如下表所示。

CRUD功能	HTTP方法
得到	读
开机自检	创造
放置/修补	更新/部分更新
删除	删除

RESTful API规范设计

API设计人员可以选择RESTful建模语言来实现API设计。以下是使用最广泛的两个方法：

OAS(昂首阔步)
RAML(RESTful API建模语言)

每个人都有其自己的API设计规范方法，每个人都有其优点和缺点，尽管它们都尊重REST架构风格。

我选择在此博客文章中使用RAML，因为我认为它是不熟悉API建模语言的人可以使用的最直观的建模语言。我将在本文中使用的REST API设计工具是教程如何使用MuleSoft的API Designer设计您的第一个API时使用的高效工具。该工具非常适合使用RAML或Swagger(OAS 2和3)设计RESTful API。但是，您可以使用任何适合您的工具。

产品用例

为了在规范中添加上下文，我将定义一个用例。假设我们公司要求一个表示产品数据的API。 REST API将公开与完整CRUD功能一致的功能，并且API规范必须记录产品数据类型并提供示例。

让我们开始定义API规范的标头。

定义API标头

我将从定义规范文件的头开始，在该头中定义API标题(出于显示目的)，资产版本以及将在其中部署实现的基本URI。

＃％RAML 1.0标题：产品APIbaseUri： http : //big-product-compnay.com/api/ {version}版本：v1

接下来，我将定义我们产品的资源表示形式。

定义资源URI

资源URI代表产品数据，正是这些URI可以执行CRUD功能，从而代表创建，读取，更新和删除操作。

为了遵守REST约定，资源URI被命名为与它所代表的实际数据相关的名词。公用资源可能如下表所示：

资源网址	数据类型
/帐户	帐户资料
/发票	发票数据
/用户	用户数据

REST风格的期望是，对GET / products端点的调用将返回产品列表(即使响应仅包含一个产品)，因此，由于资源表示集合，因此名词是复数的。 RAML语法指出资源URI必须以冒号终止：

/产品：

定义资源URI后，将使用HTTP方法指定要在这些资源上操作的CRUD功能。

为资源URI定义HTTP方法

如上所示，定义了五种HTTP方法供REST API规范的开发人员使用。

REST风格指出GET和POST HTTP方法与单个URI资源一起使用，因为它们的目标不是可识别资源，而是资源列表。相反，DELETE，PUT和PATCH HTTP方法附带一个URI变量，用于标识受影响的资源。看下面的代码。

/产品：得到：帖子：/ {productID}：pu t：删除：

请注意，如何将GET和POST方法与/ products URI一起使用，以及将PUT和DELETE与/ products / {productID} URI一起使用。

POST和PUT端点必须包括资源表示，在我们的情况下是要创建(POST)或更新(PUT)的产品。请求主体必须在规范中定义，以便调用者可以清楚地知道必须发送哪些数据以及采用哪种格式。

定义HTTP请求

为了满足REST要求以清晰的资源表示，API规范必须定义数据类型并提供有效的数据示例。在我们的案例中，这将是定义产品结构和示例的数据类型。

指定数据交换格式也是一项要求(实际上是一项强烈建议)。通常，它被定义为MIME类型，例如JSON和XML，并且可以是许多类型之一。

对于我们的用例，让我们向每个端点添加一个示例并定义MIME类型。

在产品GET，POST和PUT端点下方的RAML中，使用POST和PUT的产品数据示例定义。数据交换格式定义为application / JSON。

/产品：得到：帖子：身体：应用程序/ json：例如：{“名称”：“床”，“价格”：“ 100”}/ {productsID}：放：身体：应用程序/ json：例如：{“名称”：“床”，“价格”：“ 100”}删除：

对于对API的每个请求，都应该预期响应，并且应该在RESTful API规范中定义响应。让我们看一下这是如何完成的。

定义HTTP响应

响应于请求，调用者希望接收包含数据(或至少一条消息)和指示请求状态的HTTP状态代码的正文。 HTTP状态代码属于五类之一，如下所示：

1xx->信息性
2xx->成功
3xx->重定向
4xx->客户端错误
5xx->服务器错误

状态码的第一位数字标识响应的状态。可以在此处找到状态代码的完整列表。

对于我们的产品示例，让我们为GET和DELETE方法定义一个响应。我将为GET和DELETE请求定义一个200代码，以指示操作成功。

/产品：得到：描述：检索所有产品列表回应：200：身体：应用程序/ json：例如：{“名称”：“床”，“价格”：“ 100”}帖子：/ {productID}：pu t：删除：回应：200：描述：删除ID为{productID}的产品

现在，我们已经定义了API规范的所有主要方面，下面将它们放在一起。

全部放在一起

完整的RESTful API设计如下所示：

＃％RAML 1.0标题：产品APIbaseUri： http : //big-product-compnay.com/api/ {version}版本：v1

/产品：得到：描述：检索所有产品列表回应：200：身体：应用程序/ json：例如：{“名称”：“床”，“价格”：“ 100”}帖子：身体：应用程序/ json：例如：{“名称”：“床”，“价格”：“ 100”}/ {productID}：放：身体：应用程序/ json：例如：{“名称”：“床”，“价格”：“ 100”}删除：回应：204：描述：删除ID为{productID}的产品