DreamFactory入门指南 - 第1章REST和DreamFactory简介

DreamFactory入门指南 - 第1章REST和DreamFactory简介

 

无论您在当今的IT行业中扮演什么角色，API都是工作中不可或缺的一部分。营销人员定期将Salesforce，Pipedrive和MailChimp API集成到广告系列中，而软件开发人员则依靠Stripe，Google Maps和Twitter API来构建引人注目的Web应用程序。大厅里的数据科学家们正在努力解决使用亚马逊机器学习，Elasticsearch和IBM EventStore API的越来越笨拙的公司指标崩溃问题。同时，执行团队依靠Geckoboard，Google Analytics和Baremetrics来监控公司的进展和未来发展方向。

除了集成第三方API之外，您的组织还可能深入参与创建用于与专有数据源交互的内部API。但与上面提到的即插即用API不同，手动API开发不过是在公园散步。这个过程非常耗时，容易出错，最终会分散构建引人注目的产品和服务这一更为重要的任务。

本章向您介绍DreamFactory，一个自动REST API生成，集成和管理平台。您可以使用DreamFactory为数百个数据源生成REST API，包括MySQL和Microsoft SQL Server等数据库，包括Amazon S3在内的文件系统，Mandrill等电子邮件传递提供商。您还可以集成第三方API，包括本章开头段落中提到的所有上述服务。这为构建复杂的工作流程开辟了一个全新的可能性世界。但在我们开始介绍这篇介绍之前，一些读者可能想知道REST API是什么，更不用说为什么这么多组织依赖REST来实现他们的API。

 

＃介绍REST

如果您要设计一个理想的解决方案，用于在计算机之间传递数据（“计算机”是用来代表服务器，笔记本电脑，移动电话和任何其他连接互联网的设备的总称），它会是什么样子？

对于初学者，我们可能会考虑使用HTTP作为传输协议，因为可以快速创建通过HTTP和HTTPS进行通信的应用程序。此外，HTTP支持请求URL，可以构建它以轻松识别特定的目标资源（例如https://www.example.com/employees/42），请求方法，这些方法可以识别我们想要与之相关的内容。目标资源（例如GET（检索），POST（插入），PUT（更新），DELETE（销毁）），以URL参数和消息体的形式请求有效负载。

我们还希望合并一种可理解且可解析的消息传递格式，例如XML或JSON; 编程语言不仅可以轻松构建和导航这些格式，而且对于我们人类而言，它们也相对容易。

最后，我们希望该解决方案是可扩展的，允许集成诸如缓存，身份验证和负载平衡等功能。通过这样做，我们可以创建安全且可扩展的应用程序。

如果这样的解决方案听起来很吸引人，那么您将会喜欢使用REST API。Representational State Transfer（REST）是一个术语，用于定义体现若干特征的系统（参见https://en.wikipedia.org/wiki/Representational_state_transfer）：

• 客户端 - 服务器体系结构：通过采用客户端 - 服务器模型，基于REST API的解决方案可以包含多个应用程序和数据库服务器，以创建分布式，安全且可维护的环境。

• 统一接口：REST使用HTTP URL，HTTP方法和媒体类型声明不仅有助于实现者和最终用户容易理解的环境。

• 无状态：所有基于REST的通信都是无状态的，这意味着每个客户端请求都包含服务器响应请求所需的所有内容。目标URL，requeset方法，内容类型和API密钥只是可能包含在请求中的几个示例。

• 分层系统：支持系统分层，可以轻松引入中间件，允许在不干扰实施的情况下引入用户身份验证和授权，数据缓存，负载平衡和代理。

• 高速缓存控制：HTTP响应可以包括指示响应数据是否可高速缓存的信息，确保中间环境不会错误地提供过时数据，同时还允许可扩展性。

既然您已经了解了有关REST架构的更多信息，那么让我们回顾一下典型的REST请求和响应。

小费

在本书中，您经常会遇到资源一词。在REST上下文中，资源是可以命名的任何数据。例如，图像，员工，教室或车辆都将被称为资源。此外，资源可以是此命名数据的单个实例，也可以是集合。换句话说，员工是单身人士资源，而一组员工则是集合资源。

 

＃解析REST请求和响应

REST API集成商花费大量时间来了解如何生成正确的REST请求，以及如何解析REST响应。如前所述，这些请求和响应围绕HTTP URL，HTTP方法，请求有效负载和响应格式。在本节中，您将了解有关每个角色的更多信息。如果您不熟悉这些REST概念，那么花几分钟时间了解它们将大大减少您在以后熟悉DreamFactory时花费的时间和精力。

 

＃检索资源

正确的REST API URL模式实现是以资源（名词）为中心的实现，并将所需操作（动词）的任何指示留给随附的HTTP方法。请考虑以下请求：

GET /api/v2/employees

如果端点存在且找到记录，则REST API服务器将使用200状态代码和JSON格式的结果进行响应。例如，这是DreamFactory返回的示例响应：

{
  "resource": [
    {
      "id": 1,
      "first_name": "Georgi",
      "last_name": "Facello"
    },
    {
      "id": 2,
      "first_name": "Bezalel",
      "last_name": "Simmel"
    }
    ...
  ]
}

这种清晰度代表了典型的REST请求; 根据方法和URL，客户端正在请求员工列表非常清楚。我们知道客户端想要检索记录，因为请求是使用该GET方法提交的。将此与以下请求进行对比：

GET /api/v2/employees/find

这不是RESTful，因为实现者已将操作合并到URL中。回到原始模式，考虑如何请求特定员工：

GET /api/v2/employees/42

添加ID（通常但不总是资源的主键）表示客户端有兴趣检索与已分配值的唯一标识符相关联的员工记录42。JSON响应可能如下所示：

{
  "id": 42,
  "first_name": "Claudi",
  "last_name": "Kolinko"
}

许多REST API实现（包括DreamFactory）支持查询参数的传递以修改查询行为。例如，如果您想first_name在检索资源时仅检索字段，则DreamFactory支持fields执行此操作的参数：

GET /api/v2/employees/42?fields=first_name

响应看起来像这样：

{
  "first_name": "Claudi"
}

GET请求是幂等的，这意味着无论您提交请求多少次，都可以预期相同的结果，没有意外的副作用。将此与POST请求（下一步介绍）进行对比，这些请求被认为是非幂等的，因为如果您多次提交相同的资源创建请求，则可能会创建重复的资源。

 

＃创建资源

如果客户端希望在employees表中插入新记录，则将使用该POST方法：

POST /api/v2/employees

当然，请求需要伴随要创建的数据。这将通过请求正文传递，可能如下所示：

{
  "resource": [
    {
      "first_name": "Johnny",
      "last_name": "Football"
    }
  ]
}

 

＃更新资源

HTTP支持两种不同的更新数据方法：

• PUT：该PUT方法完全替换现有资源。这意味着无论属性值是否实际被修改，您都需要传递所有资源属性。
• PATCH：该PATCH方法仅更新现有资源的一部分，这意味着您只需提供资源主键和您要更新的属性。这通常是比更方便的更新方法PUT，尽管两者都有其优点。

使用更新资源时，PUT您将发送如下PUT请求：

PUT /api/v2/employees

您将发送请求有效内容中的所有资源属性：

{
  "resource": [
    {
      "id": 42,
      "first_name": "Johnny",
      "last_name": "Baseball"
    }
  ]
}

要更改与employees资源中找到的特定记录关联的一个或多个（但不是全部）属性，您将向URL 发送PATCH请求employees，并附带主键：

/api/v2/employees/42

假设employees表包括属性，如first_name，last_name和employee_id，但我们只需要修改的first_name值。JSON请求主体看起来像这样：

{
  "resource": [
    {
      "first_name": "Paul"
    }
  ]
}

 

＃删除资源

要删除资源，您需要向与您要删除的资源DELETE关联的端点发送请求。例如，要删除employees资源，您将引用此URL：

DELETE /api/v2/employees/42

 

＃介绍DreamFactory

鉴于我们迄今为止讨论的关于实现REST API的所有内容，自己实现一个的想法可能听起来相当令人生畏。它应该，因为它。在这样做时，您不仅要负责构建处理请求方法和URL所需的逻辑，而且还要集成身份验证和授权，生成和维护文档，以及如何理解如何理解为任意数量的第三方数据源生成工作API。

这真的只是你挑战的开始。随着您的需求增长，复杂性也会增加。考虑将每个端点业务逻辑功能添加到API所需的工作量。或者用螺栓固定API限制功能。或者添加每服务API日志记录。构建和维护这些功能所需的工作量可能是惊人的，并且肯定会分散您和您的团队的注意力，使其远离通过创建优质产品和服务来满足客户这一更为重要的目标。

幸运的是，存在一种惊人的选择。DreamFactory是一个API自动化解决方案，可以为您处理所有这些挑战，并且大多数情况下通过简单的点击式Web界面来实现。我们将通过对DreamFactory主要功能的调查来结束本章，为您提供确定DreamFactory是否是贵组织开发工具包的有用补充所需的所有信息。

 

＃自动化REST API生成

虽然DreamFactory包含许多功能，但一切都围绕着平台的自动REST API生成功能展开。仅此功能就可以产生如此巨大的影响，如果不是几个月的开发时间，它将为您的团队节省数周的未来API项目！

DreamFactory本身支持数十个数据库（包括Oracle，MySQL，MS SQL Server和MongoDB），文件系统，电子邮件传递提供商，移动通知解决方案甚至源控制服务的自动API生成功能。此外，它可以将SOAP服务转换为REST，无需对SOAP代码进行任何重构，为缓存解决方案（如Memcached和Redis）创建REST API，甚至支持使用四个受支持的脚本引擎之一从头开始编写全新服务的脚本（NodeJS，PHP，Python和V8）。

通过每个生成的API公开的REST端点的结构和数量根据数据源的类型而有所不同，但是从可用性的角度来看，您可以指望它们是“功能完整”。例如，为其中一个受支持的数据库生成的REST API包括用于执行存储过程，执行CRUD（创建，检索，更新，删除）操作甚至管理数据库的端点！

 

＃从开始抵押的API

默认情况下，所有DreamFactory REST API都是安全的，没有任何机会让您的宝贵数据暴露甚至被发生在API中的恶意第三方修改。至少所有客户都需要提供一个API密钥，DreamFactory平台管理员将通过管理控制台生成该密钥。

此外，可以使用DreamFactory的角色功能锁定API密钥功能。使用角色管理功能，您可以限制API密钥与API交互的能力，仅允许访问少数选定端点，或限制对专有GET方法的访问（这意味着您可以创建只读API）。

DreamFactory的安全功能远远超出了基于API密钥的身份验证。您可以要求用户通过各种解决方案进行登录，包括基本身份验证，LDAP，Active Directory和单点登录（SSO）。成功登录后，将为用户分配一个会话令牌，该令牌将用于验证所有后续请求的身份验证状态。

 

＃互动的OpenAPI文档

您的开发人员当然希望开始将API集成到新的和现有的应用程序中，因此需要彻底了解端点，输入参数和响应。DreamFactory通过在API自动化的同时生成此文档，自动为您创建此文档。以下屏幕截图显示了DreamFactory与MySQL REST API关联生成的一组示例文档：

文档不仅仅是提供端点列表。正如您将在后面的章节中学到的，您可以单击任何这些端点并与API进行交互！此外，您的DreamFactory管理员可以创建用户帐户，该帐户仅授予对文档的访问权限，同时防止这些帐户执行其他管理任务。

 

＃业务逻辑集成

通常情况下，您需要调整API的行为，例如验证传入的输入参数，将其他API作为请求/响应工作流的一部分调用，或者在将响应结构返回到客户端之前转换响应结构。DreamFactory的脚本功能允许您将逻辑合并到任何端点，在通信的请求或响应端运行它（或两者！）。您可以使用四种支持的脚本引擎中的任何一种，包括NodeJS，PHP，Python或V8脚本引擎。将这些脚本引擎与各种可用于这些端点的DreamFactory数据结构结合使用，天空确实是调整API行为能力的极限。

 

＃API限制

您的组织花费了数月甚至数年时间来汇总和策划宝贵的数据库，最近您的客户和其他组织一直在呼吁能够访问它。这通常通过API 货币化来完成，根据特定的定价计划为客户分配基于卷的访问。

DreamFactory的API限制功能允许您将基于卷的限制与特定用户，API密钥，REST API甚至特定请求方法相关联。启用后，DreamFactory将实时监控配置，一旦达到限制，就会向客户端返回HTTP 429状态代码（Too Many Requests）。虽然提供了方便的Web界面来管理API限制，但也可以以编程方式管理这些API限制，这意味着您可以将限制管理集成到SaaS应用程序中！

 

＃API日志和报表

无论您的组织是否需要遵守欧盟的通用数据保护法规（GDPR），或者您只想密切关注REST API的请求量和行为，您都需要集成一个强大而详细的API记录和报告解决方案。幸运的是，DreamFactory插入了Logstash，它是强大的ELK（Elasticsearch，Logstash，Kibana）堆栈的一部分。这种惊人的集成允许您创建仪表板和报告，可以提供API密钥活动，HTTP状态代码和数百个其他指标的实时监控。

 

＃结论

你有它; REST API和DreamFactory平台的全面概述，整齐地打包到本指南的开篇章节中。如果这种REST API生成和管理方法听起来太有吸引力，请继续前进到第2章，在那里您将学习如何下载，安装和配置DreamFactory平台！