PostmanにおけるJSON Schemaの活用方法

Postman APIプラットフォームは、APIライフサイクルのあらゆる段階に対応する豊富なソリューションを提供しています。長年にわたり、私たちはJSON Schemaが登場し、JSONドキュメントを記述および注釈付けするための業界標準になるまでを最前線で見守ってきました。多くの代替手段が現れては消えていきましたが、JSON SchemaはAPI仕様ムーブメントの背後にある堅牢で拡張性の高い基盤であることが間違いなく証明されました。Postmanの2022 State of the APIレポートによると、回答者の72％という驚異的な数がJSON Schemaを好ましいAPI仕様として選択しています。

JSON Schemaは今日のAPI開発に深く根ざしているため、Postman組織またはPostman APIプラットフォームにおいて、JSON Schemaが何らかの形で関わっていない場所を見つけるのは困難です。また、APIファースト開発の現代的（かつ増大する）重要性により、API仕様の使用はAPIの設計と共有において重要な役割を果たします。JSON Schemaは現在、OpenAPI、AsyncAPI、RAMLなど、世界で最も人気のあるAPI仕様技術のバックボーンとなっています。

Postman組織におけるJSON Schema

Postmanが独自のAPIを構築するためにJSON Schemaをどのように使用しているか

Postmanは、Postman APIプラットフォームを支えるクラウドツールを動かす、数十のマイクロサービスからなる複雑な分散システムを運用しています。これらのマイクロサービスは、スタンドアロンのJSON Schema定義またはOpenAPIおよびAsyncAPI仕様を通じて、JSON Schemaを使用してインターフェースをモデル化しています。これらのマイクロサービスの多くは、内部データ構造と構成ファイルの検証、および予期されるレスポンスのアサートまたはJSON Schema定義からの入力データの自動生成によるエンドツーエンドテストの実行にも、JSON Schemaを内部で使用しています。Node.js企業であるPostmanは、コードベースからOpenAPIおよびAsyncAPI定義を自動的に生成するためにTypeScriptアノテーションにどのように依存できるかを分析する取り組みを開始しました。

Postmanの分散システムの管理におけるAPI仕様の重要性を考慮して、2021年には、内部Postmanプラットフォーム内で実行されるマイクロサービスによって導入されたJSON Schema定義の多様なセットを理解するため、包括的な内部調査プロジェクトが実施されました。対応するJSON Schema定義は、再利用性、類似度、一意性比、コンテンツの種類などの特性に基づいて分析されました。再利用性と発見可能性を高めるために、Postmanは中央JSON SchemaカタログAPIとして機能する新しいマイクロサービスのアイデアを探っています。

分析のために、PostmanはPostman APIプラットフォームを支えるすべてのSQLベースのデータベースから定期的にデータを抽出します。サービスのスキーマ変更に対応するために、PostmanはSQLテーブル定義をJSON Schema定義に、行をJSONドキュメントに変換してから、Postmanの内部データウェアハウスに集約します。JSON SchemaドキュメントからSQLテーブル定義を生成し、後者を信頼できる情報源にするための初期実験がいくつか行われています。

APIを超えたJSON Schemaのユースケース

Postman組織内でのJSON Schemaの使用は、そのバックエンドサービスに限定されません。たとえば、一般的なPostmanコレクションのJSONベースのデータ形式は、JSON Schemaを使用して正式に定義されています。PostmanのNewmanコマンドラインコレクションランナーは、JSON Schemaを使用してカスタムレポーターの予期される出力を検証します。Postmanの社内クロスプラットフォームデスクトップフレームワークは、JSON Schemaを使用して、デスクトップアプリケーションのさまざまなバリアント（Stable、Canaryなど）を宣言するプロファイル定義を検証および注釈付けします。Postmanはまた、JSONを使用して定義され、JSON Schemaを使用して検証された内部C4ダイアグラムをPostmanアーキテクチャで保持しています。

2022年初頭に、PostmanはgRPCとProtocol Buffersのサポートをリリースしました。内部的には、PostmanはProtocol Buffersスキーマ定義をJSON Schema定義に、そして再びProtocol Buffersスキーマ定義に変換できます。Protocol Buffersスキーマに対応するJSON Schema定義は、gRPCペイロードコンポーザーエディターでタイプヒントとオートコンプリートを提供し、ユーザー入力を検証し、テスト目的でProtocol Buffersスキーマに一致するランダムデータを生成するために使用されます。このアプローチにより、Postmanは前述の機能を単一の統合スキーマ言語であるJSON Schemaの上に実装できます。

Postman APIプラットフォームにおけるJSON Schema

JSON Schemaは、Postman APIプラットフォームのさまざまなコンポーネントを内部で開発するために使用されるだけではありません。Postmanが提供する多くの機能は、JSON Schemaを直接使用しています。

PostmanコレクションのコンテキストにおけるJSON Schema

Postmanアプリを使用して、増加する数のAPI仕様形式をPostmanコレクションに変換できます。この記事の前半で述べたように、OpenAPI、Swagger、RAMLなど、最も人気のあるAPI仕様形式はJSON Schemaに依存しています。多くの場合、API仕様の変換ロジックでは、JSON Schema定義に一致するランダムなJSONドキュメントを生成する必要があります。

Postmanコレクションを定義する場合、ユーザーは対応するコレクションの実行時に自動的に実行されるJavaScriptベースのテストおよびプリリクエストスクリプトを定義できます。これらのスクリプトを実行するためにPostmanに埋め込まれたJavaScriptエンジンは、一般的なAJV JSON Schemaバリデーターと統合されています。これにより、Postmanユーザーは幅広いJSON Schema仕様バージョンを使用してJSON Schema検証を採用するスクリプトを記述できます。

OpenAPIのコンテキストにおけるJSON Schema

Postmanアプリは、高度なJSON Schema機能を備えた豊富なOpenAPIエディターを提供します。エディターは、オートコンプリートと構文警告を表示でき、JSON SchemaとOpenAPIエンドポイント定義の可読性とセキュリティに関して潜在的な改善領域も強調表示します。OpenAPI定義は、使用可能なエンドポイントとそれぞれのJSON Schema定義の豊富なドキュメントを生成し、オプションでGo、Java、Python、およびNode.jsで記述された対応するサーバーコードを生成するために使用されます。

Postmanを使用して定義されたAPIは、API定義だけではありません。ドキュメント、テスト、モックサーバー、モニターなどの周囲の要素があります。OpenAPI仕様を記述する場合、Postmanはこれらの各要素の整合性をAPI仕様に含まれるJSON Schema定義と照合してクロスチェックします。

Postman APIネットワーク

Postman APIプラットフォームの重要なコンポーネントは、Postman APIネットワークであり、世界最大の公開APIレジストリです。このグローバルな公開レジストリには、通常、それぞれの元の作成者によって管理されている膨大な量のAPIと対応するJSON Schema定義が含まれています。注目すべき例としては、Slack Web API、Docker HUB API、Twilio APIなどがあります。したがって、Postman APIネットワークは、本番グレードのJSON Schema定義の最大のデータセットの1つです。

PostmanとJSON Schema

JSON SchemaはPostman APIプラットフォームとAPIエコシステムの重要な構成要素であるため、Postmanは、情熱的なコアコントリビューターであるOpenJS Foundationへの参加を支援できることを光栄に思います。 - Ben Hutton氏、Greg Dennis氏、Jason Desrosiers氏、そしてJulian Berman氏 - がPostmanautsとして参加します。未来がどうなるかをすべて知ることはできませんが、PostmanはAPIの未来にJSON Schemaが不可欠であると確信しています。