本日、Cloudflare APIのOpenAPI Schemas のGA版開始をお知らせします。公開はGitHubを通じて行われ、CloudflareがAPIを追加・更新する際に定期的にアップデートしていく予定です。OpenAPIは機械可読なフォーマットでAPIの定義に広く採用されている標準です。OpenAPIスキーマで当社のAPIを幅広いツールにプラグインすることができ、当社とお客様の開発速度が上がることでしょう。社内の面ではAPIの保守と更新が容易になります。その利点に触れる前に基本的なことからお話を始めましょう。
OpenAPIとは？
インターネットはAPI（Application Programming Interfaces）をベース上に構築されることが多く、世界中のクライアントにサービスとして提供されています。これにより、コンピュータは標準化された方法で互いの通信が可能になります。OpenAPIはAPIを定義する方法について広く採用されている標準で、他のマシンがこれらの定義を確実に解析し、興味深い方法で使用できるようになります。Cloudflare独自の API Shield製品はOpenAPIスキーマを使用してスキーマ検証を行い、整形式のAPIリクエストのみがオリジンに送信されることを保証しています。
Cloudflare自体はお客様がインターネット上の他の場所から弊社のセキュリティおよびパフォーマンス製品にアクセスするために使用できるAPIを持っています。当社が独自のAPIを定義している方法について説明しましょう。以前まではJSON Hyper-Schemaという標準を使用していましたが、時間が経つにつれ、社内におけるメリットとお客様の生活を快適にするために、これまで以上に多くのツールを採用したいと思うようになりました。OpenAPIコミュニティはここ数年で大きく発展し、JSON Hyper-Schemaを使用していたときには利用できなかった多くの機能を提供してくれるようになりました。現在、当社ではOpenAPIを使用しています。
OpenAPI自体についてはこちらをご覧ください。APIを定義するためのオープンかつ十分に理解された標準があることで、この標準的な定義が読み取れる共有のツールやインフラストラクチャが使用できるようになります。少し例を見てみましょう。
CloudflareのOpenAPIスキーマの使用例
価値を確認するためにスキーマ自体を使用しなければならないお客様はそれほど多くありません。OpenAPIスキーマを活用する最初のシステムは、本日発表された新しいAPIドキュメントです。OpenAPI スキーマができたため、オープンソースツールのStoplight Elementsを活用して、この新しいドキュメントサイトの生成を支援しています。これにより、メンテナンスが困難だった以前にカスタムビルドされたサイトが廃止できました。さらに、Cloudflareの多くのエンジニアはOpenAPIに精通しているため、新しいAPIを定義するときにチームが理解できる標準を使用して新しいスキーマをより迅速に記述でき、間違いを犯す可能性は低くなります。
しかし、スキーマを直接活用する方法もあります。OpenAPIコミュニティにはスキーマのセットさえあれば使えるツールが大量にあります。モックAPIとライブラリ生成がその例です。
CloudflareのAPIをモッキングする
たとえば、CloudflareのAPIを呼び出すコードがあり、ローカルでユニットテストを実行したり、CI/CDパイプラインで統合テストを簡単に実行できるようにしたいとしましょう。実行のたびにCloudflareのAPIを呼び出すこともできますが、いくつかの理由でそうしたくない場合があります。まず、リソースの作成と削除の管理が面倒になってくるくらい頻繁にテストを実行したい場合です。それにこうしたテストの多くは必ずしもCloudflareのロジックを検証しようとしているのではなく、システム自体の動作を検証します。この場合、CloudflareのAPIをモッキングするのが理想的です。CloudflareのAPI契約に違反していないとはっきりしていて、実際のリソースの管理について詳細を気にする必要がないからです。さらに、モッキングによって、レート制限や500エラーの受信など、さまざまなシナリオをシミュレートすることができます。これにより、最終的に深刻な影響を与える可能性がある通常はまれな状況について、コードをテストできます。
例として、Stoplight Prismはテスト目的で CloudflareのAPIをモッキングに使用できます。Cloudflare のAPI Schemasのローカルコピーがあれば、以下のコマンドを実行してローカルモックサーバーのスピンアップが可能です。
そして、モックサーバーにリクエストを送るとCloudflare loudflareのAPIの利用がAPI契約に違反していないことをローカルで確認できます。
$ docker run --init --rm \
-v /home/user/git/api-schemas/openapi.yaml:/tmp/openapi.yaml \
-p 4010:4010 stoplight/prism:4 \
mock -h 0.0.0.0 /tmp/openapi.yamlつまり開発時間が早まりテスト実行時間が短縮されるのです。それと同時にAPIコントラクトの問題を統合やデプロイ前に早期発見できます。
$ curl -sX PUT localhost:4010/zones/f00/activation_check \
-Hx-auth-email:foo@bar.com -Hx-auth-key:foobarbaz | jq
{
"success": true,
"errors": [],
"messages": [],
"result": {
"id": "023e105f4ecef8ad9ca31a8372d0c353"
}
}ライブラリ生成
CloudflareにはTerraformやGoなどの多くのプログラミング言語のライブラリがあります。しかし、当社製品はありとあらゆるプログラミング言語に対応しているわけではありません。幸い、openapi generatorのようなツールを使えば、CloudflareのAPIスキーマを送り込み、さまざまな言語でライブラリを生成し、お客様のコードでCloudflareのAPIと通信できるようになります。例えば、以下のコマンドでJavaライブラリが生成できます。
そして、Javaコードでそのクライアントを使い、CloudflareのAPIとの通信を始めます。
git clone https://github.com/openapitools/openapi-generator
cd openapi-generator
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.yaml \
-g java \
-o /var/tmp/java_api_clientCloudflareがOpenAPIに移行するまでの流れ
前述したように、以前はJSON Hyper-Schemaを使ってAPIを定義していました。すでにスキーマで定義されていたエンドポイントはおよそ600個あります。以下は、あるエンドポイントがJSON Hyper-Schemaにおけるスニペットの内容です。
同じエンドポイントをOpenAPIで見てみましょう。
{
"title": "List Zones",
"description": "List, search, sort, and filter your zones.",
"rel": "collection",
"href": "zones",
"method": "GET",
"schema": {
"$ref": "definitions/zone.json#/definitions/collection_query"
},
"targetSchema": {
"$ref": "#/definitions/response_collection"
},
"cfOwnership": "www",
"cfPlanAvailability": {
"free": true,
"pro": true,
"business": true,
"enterprise": true
},
"cfPermissionsRequired": {
"enum": [
"#zone:read"
]
}
}両者はかなり似ていて、ほとんどの場合、メソッドタイプ、説明、リクエストとレスポンスの定義（これらは$refsでリンクされています）など、同じ情報がそれぞれに含まれていることがわかります。一方から他方への移行は、スキーマの定義方法の変更ではなく、スキーマを使用方法の変更に意味があります。後者のOpenAPIを解析できるツールは多数ありますが、前者のJSON Hyper-Schemaを解析できるツールははるかに少ないです。
/zones:
get:
description: List, search, sort, and filter your zones.
operationId: zone-list-zones
responses:
4xx:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/components-schemas-response_collection'
- $ref: '#/components/schemas/api-response-common-failure'
description: List Zones response failure
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/components-schemas-response_collection'
description: List Zones response
security:
- api_email: []
api_key: []
summary: List Zones
tags:
- Zone
x-cfPermissionsRequired:
enum:
- '#zone:read'
x-cfPlanAvailability:
business: true
enterprise: true
free: true
pro: trueこの 1 つのAPIがCloudflare APIを構成するすべてである場合、JSON Hyper-Schemaを手動でOpenAPIスキーマに変換するだけで簡単に終わります。しかし、600回も行うのは実に骨の折れる作業でした。チーム内で常に新しいエンドポイントを追加していることを考慮すれば、追いつくことは不可能です。また、既存の API ドキュメントが既存のJSON Hyper-Schemaを使用していた場合もあったため、移行期間中は両方のスキーマを最新の状態に保つ必要がありました。きっともっといい方法があったのでしょう。
自動コンバージョン
JSON Hyper-SchemaとOpenAPIはどちらも標準規格です。それというのも、あるフォーマットのファイルを他のフォーマットに変換することは可能であるべきだから。ですよね？そう、答えは「イエス」です。既存のJSON Hyper-Schemaをすべて取り込み、OpenAPIに完全に準拠したスキーマを出力するツールを作成しました。もちろん、これは一夜にして実現したわけではありませんが、既存のOpenAPIツールがあったので、自動変換ツールを繰り返し改善し、出力スキーマに対してOpenAPI検証ツールを実行して、変換ツールがまだ抱えている問題の確認ができたのです。
変換ツールを何度も繰り返し改良し、最終的に既存のJSON Hyper-Schemaから完全に準拠したOpenAPI仕様のスキーマを自動生成できるようになりました。このツールの作成期間中、各チームは既存のスキーマの追加と更新を続け、プロダクトコンテンツチームはAPIドキュメントを使いやすくするためにスキーマ内のテキストを更新していました。古いスキーマで変更されたものはすべて新しいスキーマに自動的に反映されるので、作業スピードを落とす必要がなかったというのが、このプロセスのメリットです。
ツールの準備ができたら、あとはJSON Hyper-Schema更新の停止し、全チームをOpenAPIスキーマに移行する時期と方法を決定するだけです。JSON Hyper-Schemaしか理解していなかったため、（今となってはもう古い）API ドキュメントは最大の懸念事項でした。デベロッパーエクスペリエンスチームとプロダクトコンテンツチームの協力により、本日、新しいAPIドキュメントが公開となり、正式にOpenAPIへ切り替わりました。
今後の展開は？
OpenAPIに完全に移行し、これまで以上に多くの機会が得られるようになりました。社内では個々のチームの負担を軽減し、API開発のスピードアップに貢献するために、どのようなツールを採用するかを検討する予定です。検討中のアイデアとして、コード表記からopenAPIスキーマを自動的に作成するのはどうかと考えています。社外の話としては、お客様が使用するプログラミング言語のライブラリを自動生成し、サポートする方法を検討するのに必要な基礎的なツールが使えるようになりました。また、スキーマを使ってどんなことができるか期待が膨らみます。何か面白いことやアイデアがあれば、どんどん私たちにもお聞かせください。