PR

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

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とは別にApicuritoApicurio 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とインテグレーションのソリューションアーキテクトとしてクラウド時代のインテグレーションのあり方を提案し、導入のための支援を行っている。

連載バックナンバー

Think IT会員サービス無料登録受付中

Think ITでは、より付加価値の高いコンテンツを会員サービスとして提供しています。会員登録を済ませてThink ITのWebサイトにログインすることでさまざまな限定特典を入手できるようになります。

Think IT会員サービスの概要とメリットをチェック

他にもこの記事が読まれています