APIファーストの設計ツール「Apicurio」「Microcks」を使ってみよう！

はじめに

これまで、APIを管理する製品として、オープンソースの「3scale」について紹介してきましたが、APIのライフサイクルにはAPIを管理する前に設計・実装・デプロイ・公開といったフェーズがあります。中でもAPIでどのようなサービスや機能を提供していくかを決めるAPIの設計フェーズは、APIの価値を決める上で非常に重要なフェーズと言えます。

そこで今回は、3scaleと関連するOSS製品として、APIの設計フェーズで役立つ「Apicurio」と「Microcks」について紹介します。

APIファーストのアプローチ

APIファーストのアプローチとは、クライアントアプリケーションにとってAPIが最初のインタフェースであると捉え、APIのコーディングや実装を行う前に、APIとしてどのような機能やデータを提供していくべきか、そのAPIの利用者を念頭に置いてAPIの仕様を決めることです。

APIファーストのアプローチにおけるアプリケーション開発には、以下のようなメリットがあります。

• フロントエンドとバックエンドのシステムを疎結合化でき、APIの実装の完了をまたずにAPIクライアントの開発を並行して行える
• 特定の開発言語やAPIの実装に依存せず、APIを「契約」として位置づけることでサービスのインタフェースとして汎用的に利用できる
• 複数のプロジェクトでAPIを再利用しやすくなり、アプリケーションの開発コストを削減できる
• APIの仕様を開発チームだけでなく、ビジネスユーザとも簡単に共有でき、APIに対するフィードバックをより早く得られる

REST APIでは、Open API InitiativeがAPIを記述するためのオープンな規格としてOpenAPI Specification(OAS)を推進しており(もともとはSwaggerをベースとした規格)、APIの仕様となるOpenAPIドキュメントはjsonまたはyaml形式で記述できます。

Apicurioのインストール

Apicurioは、OpenAPIの規格に則ったOpenAPIドキュメントをブラウザベースかつノーコディングで作成するためのオープンソースのプロジェクトです。Apicurio Studioを使用することで、APIの仕様を他のメンバーと共同編集したり、フロントエンドチームとバックエンドチームなど異なるチーム間で同じAPIの仕様を共有して各チームが個別に並行して開発することも容易になります。またGitHubなどのソースコードリポジトリと連携してAPIドキュメントのバージョン管理ができるほか、Keycloakを使用して企業内の認証基盤とSSO連携することも簡単にできるようになっています。

Apicurio Studioは公式サイトにインストール方法や使い方などが記載されているので、実際にApicurio Studioをインストールしてみたいと思います(とりあえずApicurio Studioを触ってみるだけであればLive Demoサイトで試すこともできます)。

また、Apicurio StudioはJavaのアプリケーションサーバーWildFly上で動作するWebアプリケーションで、公式サイトからダウンロードすればすぐに動作させることが可能です。例えば、現時点での最新版v0.2.46は、以下の手順でダウンロード/インストールと実行ができます。

Apicurio Studioが起動したら、ブラウザで https://localhost:8443/studio/ にアクセスするとApicurio Studioのログイン画面が表示されます(図1)(SSL証明書のセキュリティ警告が表示される場合は無視してください)。

新規登録もGitHubやGoogleのアカウントを使用してもログインできます。ログインするとダッシュボードが表示されます(図2)。

初めての起動時には、まだAPIが未登録の状態なので、[Create New API] ボタンをクリックしてAPIを登録してみましょう。ここではTemplateからPet Store Exampleを選択し、任意の名前を設定して [Create API] ボタンをクリックします(図3)。

これで、REST APIの基本情報が登録されたサンプルのPet StoreのOpenAPIドキュメントが作成されます(図4)。

[Edit API] ボタンをクリックするとOpenAPIドキュメントの編集画面に遷移します(図5)。

この画面でREST APIのリソースへのパスやRESTでやり取りされるJSONのデータタイプ、POSTやGETなどの各HTTPメソッドの操作をグラフィカルに定義できます。もちろんyamlやjson形式のソースを直接編集することもできます(図6)。

さらに右上の [Live Documentation]ボタンをクリックすると、きれいに整形されたAPIドキュメントを表示できます。なおApicurio Studioでは、OpenAPIドキュメントからHTMLページを生成するAPIドキュメンテーションツールとしてReDocを使用しています(図7)。

このように、Apicurio Studioを使うとOpenAPIドキュメントをグラフィカルに作成できますが、ソースコード管理システムのURLやファイルアップロードなどでもOpenAPIドキュメントをインポートしてAPIドキュメントを編集できます。

Microcksのインストール

次に、APIのモックサーバーとして機能するOSSのMicrocksを紹介します。MicrocksはKubernetesに対応したAPIのモックを簡単に作成できるツールで、Apicurio Studioと連携させるとAPIの実装に入る前にAPIのプロトタイピングをより高速に行えるようになります。JenkinsやTekton用のプラグイン、CLIツールなども提供されており、モックを使用した開発を継続的インテグレーション(CI)のパイプラインに組み込むこともできます。

Microcksも公式サイトにインストール方法や使い方などが記載されているので、Microcksをインストールして実際に試してみましょう。MicrocksはKubernetes/OpenShift/Docker Compose上で動作しますが、ここではOpenShiftのデスクトップ版であるMinishiftを使ってローカルマシンにインストールします。MicrocksはOpenShiftのテンプレートとして提供されているので、OpenShift/Minishiftの環境があれば簡単にインストールできます。なお、Minishiftのインストール方法はOpenShiftのコミュニティサイトを参照ください。ここではOpenShift/Minishiftがインストールされている前提で進めます。

以下のコマンドでMicrocksをローカルのMinishift環境にインストールできますが、ホスト名のIPアドレスの部分は適宜自分の環境に合わせて変えてください。なお、このコマンドではKeycloakも含めたテンプレートを使用してインストールしていますが、別のテンプレートを使用して別途インストールされたKeycloakを使用することもできます。

Microcksのコンポーネントがデプロイされたら、OpenShiftの管理コンソール (https://:8443/console/)でMicrocksのプロジェクトにアクセスすると、microcksのSpringBootのPod、KeycloakのPod、Keycloak用のPostgreSQLのPod、MongoDBのPod、Postman-runtimeのPodが表示されます(図8)。

MicrocksのデプロイによりOpenShiftのルートも自動的に作成され、http://microcks-microcks.192.168.99.100.nip.io のようなURLにアクセスするとMicrocksのログイン画面が表示されます(図9)(IPアドレスは環境によって異なるため、oc get routes コマンドで実際のルートを確認してください)。

デフォルトではKeycloak経由でOpenShiftの認証プロバイダと連携しており、OpenShift/Minishiftに登録されているユーザでログインできるようになっています。ここではMicrocksのログイン画面で[Openshift v3]のメニューをクリックし、developerユーザとしてEmail、First name、Last nameの情報でログインしてみましょう(図10)。

ログインすると、Microcksのダッシュボード画面が表示されます(図11)。

Microcksではモック対象のAPI情報をMicrocksのリポジトリに格納しており、左側のメニューから[APIs | Services]を選択すると登録されているAPI(サービス)の一覧が表示されます。インストール直後は何も登録されていないため、左のメニューから[Importers]を選択してAPI(サービス)の情報を登録していきます。また、APIツールとして有名なPostmanやSoapUIで設定した内容をエクスポートして登録することもできます。ここではSoapUIで作成済みのHello REST APIの情報を取り込んでみましょう。[Importers]メニューが選択された画面で[Create]ボタンをクリックし、インポートジョブの情報を入力します(図12)。

Name: Hello REST API
Repository URL:https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloAPI-soapui-project.xml

[Next]ボタンを2回クリックし、[Create]ボタンをクリックするとインポートジョブが作成され、実行されます(図13)。

インポートジョブが完了し、APIの情報がリポジトリに登録されると、[APIs | Services]の画面でそのAPIの情報が表示されます(図14)。

APIの詳細情報ではHello REST APIのモックのURLを確認できるので、そのAPIをテストできるようになります(図15)。

試しに、作成されたHello REST APIのモックにcurlコマンドで実行してみると、ダミーのレスポンスが返ってきます。

また、MicrocksではKeycloakを使用してユーザの権限管理を行っています。oc get routesコマンドでKeycloakのルートを表示し、管理コンソールにログインしてみましょう。以下の例の場合はhttp://keycloak-microcks.192.168.64.100.nip.ioにアクセスします(ユーザIDとパスワードはMicrocksのインストール時にコマンド引数で指定した値、ここではadmin/passwordとなります)。

Keycloakの管理コンソールにログインし、Microcksレルムでdeveloperユーザを表示します(図16)。

デフォルトではdeveloperユーザに管理者権限はないので、Microcksのリポジトリ(API情報やジョブの削除など)やユーザを管理できるように管理者権限を追加してみましょう。developerユーザを選択し、developerユーザの詳細設定画面のタブでRole Mappingsを選択します。Realm Rolesの[Available Roles]からadminをロールとして追加し、Client Rolesのドロップダウンリストからrealm-managementを、Available Rolesからmanage-usersを選択してロールとして追加します(図17)。

権限を追加すると、Microcksの画面でも設定を削除したりユーザを管理したりできるようになります(図18、19)。

Apicurio StudioとMicrocksの連携

デフォルトでApicurio StudioはMicrocksと連携はしていませんが、OpenID Connectを介して直接連携できるようになっています。設定方法はこちらに記載があります。Apicurio Studioの起動時に以下のオプションを追加します。

• MicrocksのAPIに対するURL
• MicrocksのレルムにおけるクライアントID
• Microcksのレルムにおけるクライアントシークレット
• Apicurioの画面で連携機能を表示するフラグ

ここでは、次のようなコマンドを実行してMicrocksとApicurio Studioを連携させます。

なお、クライアントシークレットの値はKeycloakの管理コンソールでClientsメニューからmicrocks-serviceaccountを選択し、Credentialsタブに表示されるSecretの値を使用します(図20)。

Microcksとの連携オプションを付けてApicurio Studioを起動すると、Pet Store APIにAPI Mockingのメニューが追加されます(図21)。

[Mock with Microcks]ボタンをクリックするとAPIのモックを作成画面が表示されるので、[Mock API]をクリックしましょう(図22)。

Microcksにモックが作成されると、作成完了画面が表示されます(図23)。

Apicurio StudioでPet Store APIの画面に戻りAPI Mockingセクションを見ると、このAPIのモックがMicrocksに作成されていることが確認できます(図24)。

[View in Microcks]ボタンをクリックするとMicrocksの画面に遷移し、Pet Store APIのモック画面が表示されます(図25)。

例えば、GET /petsを選択すると、このAPIに対するモックの情報が表示されます(図26)。

また、Mock URLのURLをコピーしてcurlコマンドを実行すると、モックのダミーの値が返ってきます。

このように、Apicurio StudioとMicrocksを組み合わせるとAPIを設計し、APIの実装を待たずしてAPIのモックを使用したAPIクライアントの開発が進められます。

おわりに

最後に、Apicurio関連のプロジェクトを紹介します。サブプロジェクトとしては、Apicurio Studioとは別にApicuritoやApicurio RegistryといったAPIに関するオープンソースのプロジェクトがあります。

Apicurito

ApicuritoはApicurio Studioの軽量版で、データベースを使用しないステートレスなアプリケーションです。Syndesisというクラウドネイティブなインテグレーション基盤にも組み込まれており、Syndesisを使うとAPIの設計・実装と他システムとの連携がノーコード／ローコードで実現できます。

Apicurio Registry

Apicurio RegistryはAPIのレジストリとして、OpenAPIだけでなくApache Avro、JSON、Protobuf、AsyncAPIなどのデータフォーマットに対応し、サービスやイベントのスキーマ情報を格納します。

これらのApicurioの関連プロジェクトについては、また別の機会に紹介したいと思います。