API Connet REST APIとは

API Connect v5では、API Connectのプラットフォームが提供する機能の一部がREST APIとして利用できました。v2018では、プラットフォームが提供する機能、WebUIでできる機能が全てREST APIで公開されているとのことです。Knowledge Center: API Connect REST APIs

REST APIの仕様は、上記Knowlege Centerのリンクからも辿れますが、IBM API Connect API Docsで公開されています。このAPIの呼び出してみます。

実行環境

API Connect v2018.4.1.2

REST APIの呼び出し

REST APIを呼び出すには、認証のための事前準備が必要です。IBM API Connect API Docsの左メニューにあるAuthenticationの作業を行う必要があります。

REST呼び出しを行うアプリケーションの登録
Bearerトークンの取得 & 実行

1. REST呼び出しを行うアプリケーションの登録

ガイドに従い実行します。
API Connect REST APIにアクセスする各クライアントアプリは、API Connectに登録する必要があるようです。登録は、API Connect Toolkit の CLIコマンドで実行します。CLIコマンドの実行には、API ConnectのCloud Managerにログインする必要があります。ログインには、ログインするユーザーが含まれるレジストリー情報が必要となります。Cloud Managerのアドレスに対して、adminでのレジストリーを確認します。

$> apic identity-providers:list --scope admin --server cloud-admin-ui.example.com
default-idp-1

次にCloud Managerにログインを行います。

$> apic login
API Connect の資格情報を入力してください
サーバーを入力してください: cloud-admin-ui.example.com
レルムを入力してください: admin/default-idp-1
ユーザー名を入力してください: admin
パスワードを入力してください: 
cloud-admin-ui.example.com に正常にログインしました

ログインは対話形式でなくとも可能です。

$> apic login --username admin --password ******** --server cloud-admin-ui.example.com --realm admin/default-idp-1
cloud-admin-ui.example.com に正常にログインしました

ログアウトは以下コマンドでできます

$> apic logout --server cloud-admin-ui.example.com
cloud-admin-ui.example.com から正常にログアウトしました

次に、REST呼び出しを行うクライアント・アプリケーションを登録します。
ガイド記載の情報を含むクライアント・アプリケーションに必要なJSONを用意します。以下は例です。client_typeは用途に応じて変更します。この記事では"ui"としています。

restclient.json

{
  "name": "restclient",
  "client_id": "restclientid", 
  "client_secret": "********",
  "client_type": "ui"
}

登録のコマンドを実行します。

$> apic registrations:create --server cloud-admin-ui.example.com rest_client.json 
restclient    [state: enabled]   https://cloud-admin-ui.example.com/api/cloud/registrations/91e047ab-b6f3-400b-a008-24b3fc9173c9

これで、REST呼び出しを行うアプリケーションの登録は終わりです。

2. Bearerトークンの取得 & 実行

API ConnectのREST APIへの呼び出しは、/api/token エンドポイントで取得するBearerトークンを使用して認証されます。REST APIを呼び出すために必要なBearerトークンを取得します。
ガイドに記載の通り、Bearerトークンを取得する要求は、Resource Owner Password Credentials付与タイプを使用したOAuth 2.0アクセストークン要求と同じで、リクエストの内容はフォームデータとしてではなくJSONペイロードとして送信する必要があります。

JSONデータに必要なものとしては以下になります。

username: REST呼び出しをするAPI Connectのユーザー
password: 上記ユーザーのパスワード
realm: 上記ユーザーが登録されているユーザー・レジストリー
client_id: 前ステップでRESTクライアントとして登録したclient_id
client_secret: 前ステップでRESTクライアントとして登録したclient_secret
grant_type: password (固定)

Cloud Managerではなく、API Managerのユーザーで実行する場合、realm、ユーザー・レジストリーが異なるため確認する必要があります。

$> apic identity-providers:list --scope provider --server cloud-admin-ui.example.com
default-idp-2

これらからガイド通りに呼び出しを行います。

$> curl -v -k -X POST -d '{"username": "user01", "password": "********", "realm": "provider/default-idp-2", "client_id": "restclientid", "client_secret": "********", "grant_type": "password"}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api-manager-ui.example.com/api/token

----省略
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxZDU1YzUwZi0yMGZiLTRmZDMtODE1NS04M2MwNzY0MzRjNTkiLCJuYW1lc3BhY2UiOiJjY2NiNzgxMC01NTVhLTQ5NzEtOWFiZi03N2FkYjYyMTMxY2U6MTg3YzMyMDktNmYyZi00YjgwLWJhZjEtZDViZGFhZWY2NjA2OmQxNmJlOGVlLTlmMGUtNDI2My04ZThmLWU5YTVkZTBhMDA1MyIsImF1ZCI6Ii9hcGkvY2xvdWQvcmVnaXN0cmF0aW9ucy85MWUwNDdhYi1iNmYzLTQwMGItYTAwOC0yNGIzZmM5MTczYzkiLCJzdWIiOiIvYXBpL3VzZXItcmVnaXN0cmllcy9jY2NiNzgxMC01NTVhLTQ5NzEtOWFiZi03N2FkYjYyMTMxY2UvMTg3YzMyMDktNmYyZi00YjgwLWJhZjEtZDViZGFhZWY2NjA2L3VzZXJzL2QxNmJlOGVlLTlmMGUtNDI2My04ZThmLWU5YTVkZTBhMDA1MyIsImlzcyI6IklCTSBBUEkgQ29ubmVjdCIsImV4cCI6MTU1ODUxODc5NywiaWF0IjoxNTU4NDg5OTk3LCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX3JlZ2lzdHJ5X3VybCI6Ii9hcGkvdXNlci1yZWdpc3RyaWVzL2NjY2I3ODEwLTU1NWEtNDk3MS05YWJmLTc3YWRiNjIxMzFjZS8xODdjMzIwOS02ZjJmLTRiODAtYmFmMS1kNWJkYWFlZjY2MDYiLCJyZWFsbSI6InByb3ZpZGVyL2RlZmF1bHQtaWRwLTIiLCJ1c2VybmFtZSI6InBvb3duZXIwMSIsImlkX3Rva2VuIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5Sm1hWEp6ZEY5dVlXMWxJam9pVDFkT1JWSXdNU0lzSW14aGMzUmZibUZ0WlNJNklsQlBJaXdpZFhObGNsOXBaQ0k2SWpVMU1qaGhNRFpsTFdZeU1tVXRORGN5T0MwNE5qZ3dMVEU1TlRoaVlUTXhOell6TnlJc0luVnpaWEp1WVcxbElqb2ljRzl2ZDI1bGNqQXhJaXdpYVdGMElqb3hOVFU0TkRnNU9UazNmUS5CSlZvZmkxTUItOWhsRXhPQVcxYk9TR0l5UUw5QUZmSkFIM2xjTVlFREI4Iiwic2NvcGVzIjpbImNsb3VkOnZpZXciLCJjbG91ZDptYW5hZ2UiLCJwcm92aWRlci1vcmc6dmlldyIsInByb3ZpZGVyLW9yZzptYW5hZ2UiLCJvcmc6dmlldyIsIm9yZzptYW5hZ2UiLCJkcmFmdHM6dmlldyIsImRyYWZ0czplZGl0IiwiY2hpbGQ6dmlldyIsImNoaWxkOmNyZWF0ZSIsImNoaWxkOm1hbmFnZSIsInByb2R1Y3Q6dmlldyIsInByb2R1Y3Q6c3RhZ2UiLCJwcm9kdWN0Om1hbmFnZSIsImFwcHJvdmFsOnZpZXciLCJhcHByb3ZhbDptYW5hZ2UiLCJhcGktYW5hbHl0aWNzOnZpZXciLCJhcGktYW5hbHl0aWNzOm1hbmFnZSIsImNvbnN1bWVyLW9yZzp2aWV3IiwiY29uc3VtZXItb3JnOm1hbmFnZSIsImFwcDp2aWV3OmFsbCIsImFwcDptYW5hZ2U6YWxsIiwibXk6dmlldyIsIm15Om1hbmFnZSIsIndlYmhvb2s6dmlldyJdfQ.P9UkAUQBsepM_WM03jf162c01_rPrYCC1xmxbPOXKmk",
    "token_type": "Bearer",
    "expires_in": 28800
* Connection #0 to host api-manager-ui.example.com left intact
}

8時間有効なBearerトークンが取得できました。
Bearerトークンを付与して、/meを呼び出してみます。

$> curl -v -k -H 'Accept: application/json' -H "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxZDU1YzUwZi0yMGZiLTRmZDMtODE1NS04M2MwNzY0MzRjNTkiLCJuYW1lc3BhY2UiOiJjY2NiNzgxMC01NTVhLTQ5NzEtOWFiZi03N2FkYjYyMTMxY2U6MTg3YzMyMDktNmYyZi00YjgwLWJhZjEtZDViZGFhZWY2NjA2OmQxNmJlOGVlLTlmMGUtNDI2My04ZThmLWU5YTVkZTBhMDA1MyIsImF1ZCI6Ii9hcGkvY2xvdWQvcmVnaXN0cmF0aW9ucy85MWUwNDdhYi1iNmYzLTQwMGItYTAwOC0yNGIzZmM5MTczYzkiLCJzdWIiOiIvYXBpL3VzZXItcmVnaXN0cmllcy9jY2NiNzgxMC01NTVhLTQ5NzEtOWFiZi03N2FkYjYyMTMxY2UvMTg3YzMyMDktNmYyZi00YjgwLWJhZjEtZDViZGFhZWY2NjA2L3VzZXJzL2QxNmJlOGVlLTlmMGUtNDI2My04ZThmLWU5YTVkZTBhMDA1MyIsImlzcyI6IklCTSBBUEkgQ29ubmVjdCIsImV4cCI6MTU1ODUxODc5NywiaWF0IjoxNTU4NDg5OTk3LCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX3JlZ2lzdHJ5X3VybCI6Ii9hcGkvdXNlci1yZWdpc3RyaWVzL2NjY2I3ODEwLTU1NWEtNDk3MS05YWJmLTc3YWRiNjIxMzFjZS8xODdjMzIwOS02ZjJmLTRiODAtYmFmMS1kNWJkYWFlZjY2MDYiLCJyZWFsbSI6InByb3ZpZGVyL2RlZmF1bHQtaWRwLTIiLCJ1c2VybmFtZSI6InBvb3duZXIwMSIsImlkX3Rva2VuIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5Sm1hWEp6ZEY5dVlXMWxJam9pVDFkT1JWSXdNU0lzSW14aGMzUmZibUZ0WlNJNklsQlBJaXdpZFhObGNsOXBaQ0k2SWpVMU1qaGhNRFpsTFdZeU1tVXRORGN5T0MwNE5qZ3dMVEU1TlRoaVlUTXhOell6TnlJc0luVnpaWEp1WVcxbElqb2ljRzl2ZDI1bGNqQXhJaXdpYVdGMElqb3hOVFU0TkRnNU9UazNmUS5CSlZvZmkxTUItOWhsRXhPQVcxYk9TR0l5UUw5QUZmSkFIM2xjTVlFREI4Iiwic2NvcGVzIjpbImNsb3VkOnZpZXciLCJjbG91ZDptYW5hZ2UiLCJwcm92aWRlci1vcmc6dmlldyIsInByb3ZpZGVyLW9yZzptYW5hZ2UiLCJvcmc6dmlldyIsIm9yZzptYW5hZ2UiLCJkcmFmdHM6dmlldyIsImRyYWZ0czplZGl0IiwiY2hpbGQ6dmlldyIsImNoaWxkOmNyZWF0ZSIsImNoaWxkOm1hbmFnZSIsInByb2R1Y3Q6dmlldyIsInByb2R1Y3Q6c3RhZ2UiLCJwcm9kdWN0Om1hbmFnZSIsImFwcHJvdmFsOnZpZXciLCJhcHByb3ZhbDptYW5hZ2UiLCJhcGktYW5hbHl0aWNzOnZpZXciLCJhcGktYW5hbHl0aWNzOm1hbmFnZSIsImNvbnN1bWVyLW9yZzp2aWV3IiwiY29uc3VtZXItb3JnOm1hbmFnZSIsImFwcDp2aWV3OmFsbCIsImFwcDptYW5hZ2U6YWxsIiwibXk6dmlldyIsIm15Om1hbmFnZSIsIndlYmhvb2s6dmlldyJdfQ.P9UkAUQBsepM_WM03jf162c01_rPrYCC1xmxbPOXKmk" https://api-manager-ui.apic2018mgmt.apitechsalesjp.com/api/me

---省略
{
    "type": "me",
    "api_version": "2.0.0",
    "name": "d16be8ee-9f0e-4263-8e8f-e9a5de0a0053",
    "state": "enabled",
    "identity_provider": "default-idp-2",
    "username": "user01",
    "email": "user01@example.com",
    "first_name": "XXX",
    "last_name": "YYY",
    "metadata": {
        "id": "5528a06e-f22e-4728-8680-1958ba317637",
        "name": "d16be8ee-9f0e-4263-8e8f-e9a5de0a0053",
        "username": "user01"
    },
    "url": "https://api-manager-ui.example.com/api/user-registries/cccb7810-555a-4971-9abf-77adb62131ce/187c3209-6f2f-4b80-baf1-d5bdaaef6606/users/d16be8ee-9f0e-4263-8e8f-e9a5de0a0053"
* Connection #0 to host api-manager-ui.example.com left intact

APIをコールしているユーザーの情報が取得できます。

API ConnectのREST APIも、Bearerトークンを付け、URLを変更し、必要に応じてパラメーターを追加することで実行可能です。

まとめ

API Connect v2018から、プラットフォームが提供するAPIがRESTで公開されています。これらを呼び出して見ました。RESTを呼び出すユーザーのロール等でアクセス制御を行うことで、REST APIのアクセス制御も可能と思われます。

API Connect v2018 の REST APIを使ってみる

API Connet REST APIとは

実行環境

REST APIの呼び出し

1. REST呼び出しを行うアプリケーションの登録

2. Bearerトークンの取得 & 実行

まとめ