Apicurioを使ってAPIカタログを公開してみよう

はじめに

最近、APIの開発をすることが多くなり、APIカタログを簡単に公開できるツールがないか探していたところ、Apicurioと呼ばれるAPI設計と管理のためのオープンソースのツールを見つけたため、今回はこちらについて紹介する。
尚、本記事ではAPIやAPIカタログという用語が頻繁に登場するが、ここでのAPIはすべてWebAPIを指す。
また、APIカタログとは、提供されているWebAPIの一覧や仕様を体系的にまとめたものを意味する。

• Apicurioとは
• Apicurio Registoryの構築
• APIカタログの登録・確認
• 実運用に向けての考察

動作環境の前提

• 動作環境：macOS Sequoia 15.3.1
• Dockerの環境構築ができていること。
• Docker-Composeの導入ができていること。

注意事項

• 掲載したソースコードはサンプルになります。
  本ソースコードを使用することで発生するいかなる損害や不利益について、当社は一切の責任を負いませんので自己の責任においてご利用ください。

Apicurioとは

Apicurioとは、API設計と管理のためのオープンソース・ツール群で、主に APIファースト開発を支援するためのツール。
代表的なコンポーネントとして、Apicurio Studio、Apicurio Registry等があり、今回はApicurio Registryを利用して、APIの公開をしていく。
Apicurioの公式サイトについては、https://www.apicur.io/ を参照。

Apicurio Registryの構築

Apicurio Registryは、APIカタログを管理するレジストリで、APIカタログの保存・検索・バージョン管理等が可能。
今回は、Docker上でApicurio Registryの構築を行う。

全体構成

システム構成図

※図は当社にて作成

システム概要

コンポーネント名	種別	役割・概要
Apicurio Registry UI	フロントエンド	ブラウザからAPIスキーマを閲覧・管理するためのUI。Apicurio-RegistryのREST APIを利用。
Apicurio Registry	サービス	APIスキーマの登録・管理を行うレジストリ。PostgreSQLに接続。
PostgreSQL	データベース	Apicurio Registryのメタデータを保存するRDBMS。

Docker-Composeの実装

version: "3.8"
services:
  # Save Apicurio API
  apicurio-postgres:
    image: postgres:13.14
    container_name: apicurio-postgres-db
    environment:
      - POSTGRES_DB=apicurio-registry
      - POSTGRES_USER=apicurio-registry
      - POSTGRES_PASSWORD=apicurio-registry
    ports:
      - "60000:5432"
    volumes:
      - ./pg_data:/var/lib/postgresql/data
    networks:
      - api_network
  # Apicurio Registry 
  apicurio-registry:
    image: apicurio/apicurio-registry
    container_name: apicurio-registry-db
    environment:
      - APICURIO_STORAGE_KIND=sql
      - APICURIO_STORAGE_SQL_KIND=postgresql
      - APICURIO_DATASOURCE_URL=jdbc:postgresql://apicurio-postgres:5432/apicurio-registry
      - APICURIO_DATASOURCE_USERNAME=apicurio-registry
      - APICURIO_DATASOURCE_PASSWORD=apicurio-registry
      - QUARKUS_HTTP_CORS=true
      - QUARKUS_HTTP_CORS_ORIGINS=http://localhost:60002
      - QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_METHODS=GET,PUT,POST,DELETE,OPTIONS
      - QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_HEADERS=accept,authorization,content-type,x-requested-with
    ports:
      - "60001:8080"
    networks:
      - api_network
    depends_on:
      - apicurio-postgres
  # Apicurio Registry UI(front end)
  apicurio-registry-ui:
    image: apicurio/apicurio-registry-ui
    container_name: apicurio-registry-ui-db
    environment:
      - REGISTRY_API_URL=http://localhost:60001/apis/registry/v3
    ports:
      - "60002:8080"
    networks:
      - api_network
    depends_on:
      - apicurio-registry
 
networks:
  api_network:
    driver: bridge 

環境変数一覧

サービス	環境変数	値	解説
apicurio-postgres	POSTGRES_DB	apicurio-registry	PostgreSQLで作成されるデータベース名
	POSTGRES_USER	apicurio-registry	DB接続用ユーザー名
	POSTGRES_PASSWORD	apicurio-registry	DB接続用パスワード
apicurio-registry	APICURIO_STORAGE_KIND	sql	ストレージの種類をSQLに設定
	APICURIO_STORAGE_SQL_KIND	postgresql	使用するSQL DBをPostgreSQLに設定
	APICURIO_DATASOURCE_URL	jdbc:postgresql://apicurio-postgres:5432/apicurio-registry	JDBC接続URL（DBホスト名・ポート・DB名を含む）
	APICURIO_DATASOURCE_USERNAME	apicurio-registry	DB接続用ユーザー名
	APICURIO_DATASOURCE_PASSWORD	apicurio-registry	DB接続用パスワード
	QUARKUS_HTTP_CORS	true	CORS（クロスオリジンリソース共有）を有効化
	QUARKUS_HTTP_CORS_ORIGINS	http://localhost:60002	許可するアクセス元のオリジン
	QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_METHODS	GET,PUT,POST,DELETE,OPTIONS	許可するHTTPメソッド
	QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_HEADERS	accept,authorization,content-type,x-requested-with	許可するHTTPリクエストヘッダ
apicurio-registry-ui	REGISTRY_API_URL	http://localhost:60001/apis/registry/v3	Apicurio Registry APIのエンドポイントURL

Docker-Composeの実行

ディレクトリは任意で、上記のdocker-compose.yamlを実行する。
実行時、PostgreSQLのDB起動完了よりも、Apicurio Registryの方が早く起動しエラーになることがある。
その場合、PostgreSQL起動完了後、Apicurio Registy、Apicurio Registry UIの2つを再起動すれば解消される。

docker-compose -p apicurio up -d

Apicurio画面の確認

ブラウザで以下のURLを指定すると、Apicurioの画面が起動する。

http://localhost:60002

APIカタログの登録・確認

APIカタログの登録

以下の例では、必要最低限の内容で登録を実施。

• Create artifactを押下
  

• 以下を入力しNextを押下
  ・Group Id：globex
  ・Artifact Id：ProductCatalogAPI
  

• 何も入力しないでNextを押下
  

• Contentの所にAPIのカタログ(OASに沿ったyaml)ファイルを指定し、Createを押下
  

• 何も入力しないでCreateを押下し登録が完了
  

登録したAPIカタログの確認

トップ画面を開くと先ほど登録したAPIが一覧上に表示される。

• ProductCatalogAPIリンクを押下
  

• Versionsタブを押下
  

• 1 のリンクを押下
  

• Documentationタブを押下
  

• APIカタログが表示される。
  

実運用に向けての考察

今回、APIのカタログはWeb画面にて登録をしたが、実運用では、GitOps等を使い自動登録していく運用が望ましい。
また、複数のシステムでAPIカタログを公開していく事になるため、権限管理も適切に行う必要がある。
Apicurio-Registryは、API経由でカタログの登録が可能であったり、KeyClockとの連携もサポートされているため、実運用に向け、適用していく事は十分可能であるが、引き続き他製品との組み合わせによる効果も見ていく。