Red Hatの新しいマネージドサービス "Red Hat OpenShift API Designer" を活用して同期・非同期に対応したAPIをグラフィカルに設計しよう！

こんにちは。Red Hatでソリューションアーキテクトをしている杉本拓です。 Red Hatのマネージドサービスについては以前の赤帽ブログでも紹介したように、マネージドのOpenShift環境で様々なマネージドサービスが利用可能になっています。

Application Services:

Red Hat OpenShift API Management
Red Hat OpenShift Streams for Apache Kafka
Red Hat OpenShift Service Registry
Red Hat OpenShift Connectors

Data Services:

Red Hat OpenShift Data Science
Red Hat OpenShift Database Access

今回は上記に加えて新しく追加されたマネージドのApplication Servicesの一つであるRed Hat OpenShift API Designerについて紹介したいと思います（この記事執筆時点の2022年9月ではService Previewです）。

Red Hat OpenShift API Designerとは

OpenShift API DesignerのベースとなっているOSSはApicurio Studioで、以前のニュースレターでも少し紹介をさせて頂いています。OpenShift API Designerは、Red Hatのマネージドサービスの利用者で Red Hat Hybrid Cloud Console にアカウントがあれば誰でも無料で利用可能なサービスとなっており、ブラウザを使用してGUIベースでOpenAPI (Swagger) に準拠したAPIドキュメント作成したり、JSON Schemaなどのスキーマを簡単に作成できるようにするためのツールです。APIドキュメントをグラフィカルに定義するためのツールは他にもありますが、このRed Hat OpenShift API Designerでは、REST APIの仕様を記述するためのOpenAPIだけでなく、イベント駆動型アーキテクチャにおける非同期なAPIを定義するためのAsyncAPIにも対応しており、Apache Avro/JSON Schema/Google Protocol Buffers (Protobuf)などのスキーマもブラウザベースで定義することができるようになっており、それがマネージドサービスとして利用できるようになっています。

このOpenShift API Designerの主なユースケースとしては以下の2つになります：

コントラクト (API) ファーストによるアプリケーション開発
Kafkaのクライアントアプリケーションで利用されるスキーマの定義

さらに以下のようなRed Hatの別のマネージドサービスと一緒に利用することでハイブリッドクラウドな環境で同期・非同期のAPIに対応したAPI設計をグラフィカルに簡単に行うことができるようになります。

Red Hat OpenShift Service Registry: Red Hat OpenShift Service Registryと連携することで、OpenShift Service RegistryからAPIドキュメントやスキーマ定義をOpenShift API Designerにインポートして編集したり、OpenShift API Designerで作成したAPIドキュメントやスキーマ定義をOpenShift Service Registryにエクスポートすることができるようになるため、OpenShift Service RegistryでAPIドキュメントやスキーマ定義を一元管理することができるようになっています。
Red Hat OpenShift API Management: OpenShift API Designerで作成したAPIドキュメントをAPI管理のサービスであるOpenShift API Managementに取り込んで、そのAPIを管理していくことができます。
Red Hat OpenShift Streams for Apache Kafka: Red HatのマネージドのKafkaであるOpenShift Streams for Apache KafkaでProduce/Consumeされるメッセージのスキーマを、OpenShift API Designerで編集することができるようになります（Service Previewでは未実装）。

Red Hat OpenShift API Designerの使い方

では、このOpenShift API Designerをどのようにして使うのか、その使い方を簡単に紹介していきましょう。前提として Red Hat Hybrid Cloud Console でのRed Hatアカウントが必要となるため、もしまだアカウントをお持ちでない場合は Red Hat Hybrid Cloud Console の画面に従ってアカウントを作成してください。

Red Hat Hybrid Cloud Console にログインして左のApplication and Data Servicesメニューを選択すると、以下のような画面が表示され、各マネージドサービスはここからアクセスできるようになっています。

左のメニューからAPI DesignerをクリックしてAPIドキュメントとスキーマ定義を行っていくことができます。なおこの記事執筆時の2022年9月ではService Previewのため、ベータ環境で利用するための確認のダイアログが表示されます。確認して次に進むとAPI Designerの画面が表示されます。

[Create design]をクリックすると、APIとスキーマの新規作成画面が表示されます。

ここでは試しにPet Store Exampleを選択し、OpenAPIのドキュメントを作成してみましょう。TypeのリストからOpenAPIを選択し、NameやDescription の値は任意で、Version はデフォルトのままで構いません。

この例ではAPIドキュメントのNameの値としてMy Pet Store APIを設定し、APIドキュメントを作成していますので、以下のようにMy Pet Store API という名前のAPIドキュメントが作成されます。

以下のようにAPIのURLパスの /pets を選択すると、そのAPIのエンドポイントごとにパラメータや戻り値など、YAMLやJSONを編集しなくてもAPIの詳細を設定していくことができるようになっています。

APIドキュメントを保存したら、以下のようにメニューから[Export design to Service Registry]を選択することで、そのAPI仕様やスキーマ定義をRed Hat OpenShift Service Registryにエクスポートすることができるようになっています。

実際に[Export design to Service Registry]を選択すると、以下のようにService Registryのインスタンスを選択することができるようになります。ただしService Registryは事前にインスタンスが作成されていることが前提となります（以下の画面ではmy-service-registryという名前のRegistryインスタンスを使用）。エクスポートの設定として、Group/ID/Versionに任意の値を指定することが可能です。特に指定しない場合、Groupはデフォルトグループが選択され、IDとVersionの値は自動生成されます。

実際にエクスポートすると、Hybrid Cloud ConsoleのService Registryの画面で先程エクスポートしたMy Pet Store APIがmy-service-registryというService Registryのインスタンスに格納されていることが分かります。

Service Registryの画面でもAPI仕様のドキュメントが画面に表示され、Service Registryに格納されているAPIドキュメントやスキーマ定義の情報はService Registryで確認し、バージョン管理することができるようになっています。

上のステップではAPI DesignerでAPIドキュメントを作成し、それをService Registryにエクスポートする手順を示していましたが、既にAPIドキュメントが存在している場合には、Service Registry/APIドキュメントのURL/ファイルからAPI DesignerにインポートしてそのAPIドキュメントを編集することが可能になっています。

最後に

以上のように、API Designerを使うことでAPIの設計をグラフィカルに簡単に行うことができ、さらにService Registryと連携させることで企業内でのAPIの標準化を推進することができるようになります。また同期通信のためのOpenAPIだけではなく、非同期通信のためのAsyncAPIにも対応しているので、REST APIとイベント駆動型アーキテクチャを適材適所で使い分けて設計や管理は一元的に行うことができるようになります。Hybrid Cloud ConsoleにアカウントがあればAPI DesignerもService Registryも無料で使うことができるのでぜひ試してみてください。その他のRed Hatのクラウドサービスも無料で試すことができるのでぜひ一緒に使っていただければと思います。