介绍 

目前，诸多应用程序通过开放授权框架（OAuth）来安全、可靠、高效地访问各种服务中的资源。InterSystems IRIS目前已兼容OAuth 2.0框架。事实上社区有一篇关于OAuth 2.0和InterSystems IRIS的精彩文章，链接如下。 

然而，随着API管理工具的出现，一些组织开始将其用作单点身份验证，从而防止未经授权的请求到达下游服务，并将授权/身份验证复杂性从服务本身分离出来。 

您可能知道，InterSystems已经推出了自己的API管理工具，即InterSystems API Management （IAM），以IRIS Enterprise license（IRIS Community版本不含此功能）的形式提供。这里是社区另一篇介绍InterSystems AIM的精华帖。 

这是三篇系列文章中的第一篇，该系列文章将展示如何在OAuth 2.0标准下使用IAM简单地为IRIS中的未经验证的服务添加安全性。 

第一部分将介绍OAuth 2.0相关背景，以及IRIS和IAM的初始定义和配置，以帮助读者理解确保服务安全的整个过程。 

本系列文章的后续部分还将介绍两种使用IAM保护服务的可能的场景。在第一种场景中，IAM只验证传入请求中的访问令牌，如果验证成功，则将请求转发到后端。在第二种场景中，IAM将生成一个访问令牌（充当授权服务器）并对其进行验证。 

什么是npm-iris？ 

NPM是“No Project Mess（项目不乱）”的缩写。 

NPM是使用Intersystems IRIS和Bootstrp 4建成的项目和任务管理应用程序。 

NPM的创建初衷是通过一个简单直观的项目和任务管理软件，帮助开发者和小型商业公司降低日常问题的复杂度。 

它能提供不同的任务视图，包括电子表格、看板、日历，甚至甘特图！ 

为什么？ 

在不同的团队中工作，您会发现不同的人喜欢不同的工具。 

所以，有时您会在一个项目中使用甘特图，在另一个项目中使用看板，在其他项目中使用纸上的列表…… 

NPM专注于任务。无论您和您的团队喜欢以哪种方式查看。只需单击并更改您的视图。 

功能 

• 初始安装 
• 项目 
• 用户 
• 任务 - 创建和管理任务 

• 调度程序 - 任务的日历视图 
• 看板 - 用看板风格管理您的任务 
• 甘特图 - 使用甘特图查看截止日期、里程碑和进度 

新特性/改进的路线图 

• OAuth2身份验证 

• 项目/团队/用户的安全性 
• 时间跟踪 

• 自定义日历（假期） 
• 支持附件 
• 利用AppS.REST框架 
• Vue.js版本 
• Home面板，可以查看活动的概况 

试一下这款应用程序！ 
http://npm-iris.eastus.cloudapp.azure.com:52773/npm/home.csp  

假设您想编写一些真正的web应用程序，例如medium.com网站的简单克隆。这类应用程序可以在后端使用任何不同的语言编写，也可以使用前端的任何框架编写。编写这样一个应用程序有很多方法，你也可以看看这个项目。它为完全相同的应用程序提供了一堆前端和后端实现。您可以轻松组合它们，任何所选前端应该与任何后端搭配。

我来介绍一下这个使用后端InterSystems IRIS来实现后端的相同的应用程序。  

在本文中，我想谈一谈规范优先的 REST API 开发方式。

传统的代码优先 REST API 开发是这样的：

• 编写代码
• 使其支持 REST
• 形成文档（成为 REST API）

规范优先遵循同样的步骤，不过是反过来的。 我们先制定规范（同时兼做文档），然后根据它生成一个样板 REST 应用，最后编写一些业务逻辑。

这是有好处的，因为：

• 对于想要使用你的 REST API 的外部或前端开发者，你总是有相关且有用的文档
• 使用 OAS (Swagger) 创建的规范可以导入各种工具，从而进行编辑、客户端生成、API 管理、单元测试和自动化，或者许多其他任务的简化
• 改进了 API 架构。 在代码优先的方式中，API 是逐个方法开发的，因此开发者很容易失去对整体 API 架构的跟踪，但在规范优先的方式中，开发者被强制从 API 使用者的角度与 API 进行交互，这通常有助于设计出更简洁的 API 架构
• 更快的开发速度 - 由于所有样板代码都是自动生成的，你无需编写代码，只需开发业务逻辑。
• 更快的反馈循环 - 使用者可以立即查看 API，并且只需修改规范即可轻松提供建议 让我们以规范优先的方式开发 API 吧！

RESTful 应用程序编程接口 (API) 设计和文档编制初学者指南。 通过示例，您将学习一些常见的 RESTful API 模式。

在阅读之前

您需要知道

• 如何在 Ensemble 中创建 RESTful Web 服务
• 如何在 Ensemble 中使用 RESTful Web 服务
• 如何传递服务参数
• 如何返回服务结果

什么是服务 API？

什么是应用程序编程接口？ 是具体化的东西吗？ 是单一编程单元吗？ API 的作用是什么？ 在我看来，API 是由程序代码以间接方式决定的。 但完全定义的 API 是由运行可执行程序的容器（由部署设置控制）提供的。 因此，我宁愿将 API 定义为服务的公共描述。 该描述可以是人类可读的，也可以仅机器可读， 或者两者均可。 API 用于与将要使用服务的人员共享有关服务的基本信息。 API 说明了服务的作用、使用环境、功能以及管理的数据结构等。

在过去的好时光，“编制程序文档”或多或少是一种“必要之恶”。 现代编程语言通过在程序源码中引入声明来强制编制文档。 虽然声明是“机器人”可读的文档，但通过使用工具（runoff、Java doc...），可以提取信息并将其格式化成人类可读的格式。 即使没有在源码中添加任何一行真正的文档，这些工具仍然能够生成少量文本。

关注开发者社区全栈竞赛的朋友会知道，我提交了一个名为qewd-conduit的参赛作品。我想总结一下，为什么我认为您应该花点时间来看看这个作品。

qewd-conduit 使用基于 Node.js 的 QEWD 框架和 IRIS，可以为 RealWorld Conduit 应用程序实现后端 REST API：

https://github.com/gothinkster/realworld

这个方案很酷，它提供了一个平台，让很多人可以为特定应用程序的后端和前端，实现不同的技术解决方案。而qewd-conduit只是符合相同REST API后端规范的众多解决方案之一。同样，要实现完全相同的UI/UX，您可以尝试使用众多不同前端客户端中的任何一个，并通过REST与包括QEWD-Conduit在内的任何Conduit后端集成。

这样就可以用各种不同的框架和技术，去执行完全相同的任务，从而对不同的框架和技术进行比较和对比。

RealWorld应用程序很好地平衡了相关性和非琐碎性（不仅仅是ToDo应用程序！），并且也不是太复杂，无论是在UI/UX还是在后端API方面。因此便于展示和说明如何使用特定技术来实现RealWorld的指定功能。

最近，我需要从持久类和序列类生成一个 Swagger 规范，所以我发布了我的代码（它并不完整 - 你仍然需要处理应用程序的细节，但这是一个开始）。 代码在这里。

假设你有下面的类：