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

連載 [第5回] :

2020年3月12日(木)

はじめに

これまで、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は、以下の手順でダウンロード/インストールと実行ができます。

$ mkdir ~/apicurio-studio
$ cd ~/apicurio-studio
$ curl -L https://github.com/Apicurio/apicurio-studio/releases/download/v0.2.46.Final/apicurio-studio-0.2.46.Final-quickstart.zip -o apicurio-studio-0.2.46.Final-quickstart.zip
$ unzip apicurio-studio-0.2.46.Final-quickstart.zip
$ cd apicurio-studio-0.2.46.Final
$ ./bin/standalone.sh -c standalone-apicurio.xml

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

図1：Apicurio Studioのログイン画面

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

図2：Apicurio Studioのダッシュボード

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

図3：APIの登録

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

図4：Pet StoreのOpenAPIドキュメントが作成された

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

図5：OpenAPIドキュメントの編集画面

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

図6：各HTTPメソッドの操作をグラフィカルに定義できる

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

図7：各HTTPメソッドの操作をグラフィカルに定義できる

このように、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を使用することもできます。

$ oc login -u developer
$ oc new-project microcks --display-name="Microcks"
$ oc login -u system:admin
$ oc create -f https://raw.githubusercontent.com/microcks/microcks/master/install/openshift/openshift-ephemeral-full-template.yml -n openshift
$ oc new-app --template=microcks-ephemeral \
   --param=APP_ROUTE_HOSTNAME=microcks-microcks.192.168.99.100.nip.io \
   --param=KEYCLOAK_ROUTE_HOSTNAME=keycloak-microcks.192.168.99.100.nip.io \
   --param=OPENSHIFT_MASTER=https://192.168.99.100:8443 \
   --param=OPENSHIFT_OAUTH_CLIENT_NAME=microcks-client \
   --param=KEYCLOAK_ADMIN_USERNAME=admin \
   --param=KEYCLOAK_ADMIN_PASSWORD=password

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

図8：microcksのSpringBoot、Keycloak、Keycloak用のPostgreSQL、MongoDB、Postman-runtimeのPodが表示される

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

図9：Microcksのログイン画面が表示される

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

図10：developerユーザとしてEmail、First name、Last nameの情報でログイン

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

図11：Microcksのダッシュボード画面

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

図12：SoapUIで作成済みのHello REST APIの情報を取り込む

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

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

図13：インポートジョブが作成／実行される

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

図14：インポートジョブ終了後に登録されたAPIの情報が表示される

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

図15：APIの詳細情報ではHello REST APIのモックのURLからテストも可能

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

$ curl http://microcks-microcks.192.168.64.100.nip.io/rest/Hello+API+Mock/0.8/v1/hello
{
	'name':'David',
	'greeting':'Hello David !'
}

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

$ oc get routes
NAME       HOST/PORT                                PATH      SERVICES            PORT       TERMINATION   WILDCARD
keycloak   keycloak-microcks.192.168.64.100.nip.io             microcks-keycloak   keycloak                 None
microcks   microcks-microcks.192.168.64.100.nip.io             microcks            spring                   None

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

図16：Keycloakの管理コンソールからMicrocksレルムでdeveloperユーザを表示

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

図17：developerユーザに管理者権限を追加する

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

図18：Microcksの画面でも設定を削除したり…

図19：ユーザを管理したりできるようになる

Apicurio StudioとMicrocksの連携

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

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

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

$ ./bin/standalone.sh    -c standalone-apicurio.xml \
-Dapicurio.hub.microcks.api=http://microcks-microcks.192.168.64.100.nip.io/api \
-Dapicurio.hub.microcks.clientId=microcks-serviceaccount \
-Dapicurio.hub.microcks.clientSecret=98e07557-27d0-4f1a-be00-a382a29402fe \
-Dapicurio-ui.feature.microcks=true

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

図20：クライアントシークレットの値にはCredentialsタブに表示されるSecretの値を使用

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

図21：Pet Store APIにAPI Mockingのメニューが追加された

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

図22：モックの作成画面

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

図23：モックの作成が完了した

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

図24：Pet Store API画面でAPIのモックが作成されているを確認

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

図25：Pet Store APIのモック画面

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

図26：GET /petsのAPIに対するモック情報が表示される

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

$ curl http://microcks-microcks.192.168.64.100.nip.io/rest/Pet+Store+APIs/1.0.0/pets
[{"id":1,"name":"Zaza","tag":"cat"},{"id":2,"name":"Tigresse","tag":"cat"},{"id":3,"name":"Maki","tag":"cat"},{"id":4,"name":"Toufik","tag":"cat"}]

このように、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の関連プロジェクトについては、また別の機会に紹介したいと思います。

著者

杉本拓

この著者の記事一覧この著者の
記事一覧

レッドハット株式会社

外資系ソフトウェアベンダーにおいて、SOA、分散システム、アジャイル開発、デジタルマーケティング、コンテンツ管理などの分野でのコンサルティング業務に従事。2016年よりRed Hatにおいて、APIとインテグレーションのソリューションアーキテクトとしてクラウド時代のインテグレーションのあり方を提案し、導入のための支援を行っている。