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ドキュメントを編集できます。

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

連載バックナンバー

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

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

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

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