ソフトウェア開発ライフサイクル、およびAPIのライフサイクルにおける重要なステップとして、ますます多くの組織が設計を取り入れている一方で、APIを大規模に効果的に設計する方法を見つけ出した組織はごくわずかです。単一のチーム内で限られた数のサービスに取り組んでいる場合、設計は管理しやすく、PDFスタイルのガイドやWikiページに頼るだけで全員の足並みを揃えることができるかもしれません。しかし、その設計プロセスを複数のチームや数百、さらには数千もの異なるAPIにスケールする必要がある場合はどうなるでしょうか？
実際にスケールする設計プロセスを構築する
弊社は、チームがAPIの設計とドキュメント作成に協力する方法を変えるために、SwaggerHubを立ち上げました。この1年間、私たちは何百人ものSwaggerHubユーザーと話し合い、彼らがどのように設計プロセスを複数のチームや増加するAPIにスケールできたかをよりよく理解しました。CrowdFlowerのVP EngineeringであるCameron Befus氏は、スケーラブルなAPI設計のためにオープンソースのSwagger設計ツールからSwaggerHubに移行した経験を次のように説明しています。
Crowdflowerは以前からSwaggerを使ってAPIを定義してきましたが、SwaggerHubのおかげでそのプロセスが格段に簡単になりました。新しいサービスを設計する際にコラボレーションを促進し、それらのサービスのドキュメント作成と統合テストをはるかに簡単にするSwaggerやSwaggerHubのような素晴らしいツールは、私たちのチームにとって非常に役立っています。
BonotelのCIOであるScot Hastings氏も、最近のAPIプロジェクトで新しいデザインプロセスを立ち上げた経験を共有しています。
プロジェクトを進めるにつれて、プロセスを加速し、より効率的にする必要があることに気づきました。ユーザーインターフェースを自動生成し、内部チームと外部チーム間のコラボレーションを煩わしさやコミュニケーションの問題なく促進したいと考えました…「RESTful APIをより迅速に設計・開発できるようになったことで、新しいサービスやサービスアップデートをより早く市場に投入できるようになりました」とHastings氏は述べています。「これにより、SwaggerHubは当社のソフトウェア開発ライフサイクルの重要な要素となっています。」
CrowdFlowerやBonotelのような組織は、API設計にOpenAPI (Swagger) を標準化し、APIワークフローにシームレスに適合し、SwaggerHubでAPI設計のコラボレーションをより効果的に行えるツールを採用することで、API設計をスケールすることができました。また、彼らは、API設計プロセスを成功裏にスケールさせたチームに見られたいくつかの重要な原則を代表しています。設計プロセスをスケールする準備はできていますか？以下に、実行する必要があるいくつかの重要な手順を示します。
1. チームを連携させる
優れたAPI設計は、API開発ライフサイクルに関わるすべてのステークホルダー間の効果的な調整に依存します。チームが設計要件について連携していない場合、または適切な人々が設計変更に必要な可視性を得られない場合、少数のAPIを超えてスケールしようとすると摩擦が生じます。組織が設計プロセスについてチームメンバーを連携させようとする一般的な方法の1つは、ConfluenceやGitHubのようなコラボレーションツールを使用することです。しかし、これらのツールはソフトウェア開発ライフサイクルにおいて重要な役割を果たす一方で、API設計ワークフローの管理という特定のユースケースに設定するのは複雑になる可能性があります。SwaggerHubは、APIのライフサイクル全体を通じてチームが連携を保てるように構築されました。SwaggerHub内では、組織を作成し、チームメンバーを招待してAPIの設計とドキュメント作成で共同作業を行うことができます。組織のオーナーは、チームメンバーに役割を割り当て、設計プロセスへの関与に基づいてアクセスを管理できます。SwaggerHubでのコラボレーションの詳細はこちらをご覧ください。
2. 設計プロセスの可視性を向上させる
API設計プロセスをスケールしようとする際にチームが直面する可能性のある連携の課題と同様に、チーム全体の可視性を向上させるという困難な課題もあります。多くの場合、チームはSwagger EditorやSwagger UIのようなオープンソースのSwaggerツールからAPI設計の旅を始めます。これらのツールはAPIを効果的にモデリングし、視覚化するために必要な機能を提供しますが、大規模なAPIチームのコラボレーション要件を促進するようには構築されていません。API設計にOpenAPIを使用している場合、チーム全体がさまざまなサービスの設計作業にアクセスできる中央の場所を提供する必要があります。また、変更が発生したときに適切な人々に通知が届いていることを確認し、可視性を個別のメール、Slackメッセージ、GitHubチケットに限定しないようにする必要があります。
3. 依存関係の削減
API開発は複雑なプロセスであるだけでなく、関係するチームにとって時間がかかるプロセスにもなり得ます。チーム間の依存関係は、設計段階を超えてコード生成、ドキュメント作成、テストケース作成に進みたいチームの速度を低下させる最大の要因の1つとなる可能性があります。チームが依存関係を減らし、開発を加速できる方法の1つは、APIの「モック化」または仮想化です。SwaggerHubのAPI Auto Mocking連携は、仕様で定義された静的応答を使用してAPIのモックを作成および維持します。SwaggerHubで新しいAPIを作成する際に自動的にモックを作成することも、後でいつでも手動で作成することもできます。モックは、開発者が実装する前に、APIを設計する際にテストするのに役立ちます。また、この連携により、バックエンドが準備できる前でも、クライアントアプリケーション開発者が自分の作業を開始できます。コードを1行も書かずに、APIコンシューマーがモックに対してクライアントを開発できるようにすることができ、互換性のある現実的なペイロードで応答することが保証されます。さらに重要なのは、モデル定義内の「example」コンストラクトを使用することで、OAS定義でペイロードを直接調整できることです。
4. 設計要件の設定と実施
企業のAPIへの投資は長期的な取り組みです。設計標準は、APIの実装を改善するだけでなく、APIの更新方法や新しいAPIの開発方法も決定します。設計ガイドラインが設定されると、それを基盤としてチームがAPIを開発することが容易になり、組織は設計および開発プロセスをスケールできます。設計はクライアントとサービスがどのように相互作用するかを定義するため、設計に違いがあると、サービスの開発フェーズで混乱とオーバーヘッドが生じます。これらの不整合は増殖するばかりで、その影響はAPIライフサイクル全体に拡大します。例えば、リソースに不整合な命名規則を持つAPIは、実装中にコントローラで異なる命名スタイルを持つ可能性があります。SwaggerHubが設計の一貫性の問題に対処する方法の1つは、組み込みのスタイルバリデーターを使用して、API定義が特定の記述標準と一致するかどうかをチェックすることです。例えば、企業のガイドラインでは、すべてのプロパティに例を指定する必要がある場合があります。スタイルバリデーターは、このようなチェックを自動化するのに役立ちます。スタイルバリデーターの統合を作成する際に、実行するチェックを指定します。
5. 設計における再利用性の向上
SwaggerツールとOASを使用してAPIを定義しているAPIチームからよく聞くことの1つは、何百ものAPIにわたって複数のエンドポイントを定義する際に、設計プロセスが非常に退屈になり得るということです。これは特に、エンドポイントが共通の構文を共有し、同様の定義、パス項目、パラメーター、および応答を持つ場合に当てはまります。すべてのエンドポイントを個別に繰り返し定義する必要があるため、設計プロセスが遅くなり、API設計に矛盾が生じる可能性があります。そのため、SwaggerHubは設計プロセスに**ドメイン**の概念を導入しました。ドメインは、複数のAPIと他のドメイン間で共有できる再利用可能なコンポーネントです。ドメインには、定義、パス項目、パラメーター、応答などのコンポーネントを含めることができます。ユーザーはドメインを作成およびバージョン管理し、その中に格納できる再利用可能なコンポーネントを定義できます。これらのコンポーネントは、ユーザーまたはAPIの共同作業者によって、他のAPIまたはドメインから参照できます。
6. 信頼するツールとの統合
設計からドキュメント化、構築、APIのデプロイまでを迅速に進めることができることは、スケーラブルなAPI設計プロセスを確立するために不可欠です。APIライフサイクルの初期段階を超えて進もうとするときに摩擦が生じると、最高の設計標準でさえAPI設計をスケールするのに役立ちません。APIベンダーがこの問題に対処しようと試みた方法の1つは、API管理により適したツールの最上位に、追加の設計機能を構築することでした。オールインワンソリューションがあることは素晴らしいですが、新しいツールを導入したいときに柔軟性がほとんどない単一のソリューションに組織が閉じ込められることも必要になります。SwaggerHubでは、異なるアプローチを取りました。チームがAPI設計プロセスの「真の源」として使用できるワールドクラスのAPI設計プラットフォームを構築し、その後、Apigee、AWS、Microsoft Azure、IBM API ConnectなどのAPIゲートウェイ、Bitbucket、GitHub、GitLabなどのソースコード管理プラットフォーム、機能テスト用のSoapUIなどのチームが信頼するツールへのシームレスな統合を提供しています。SwaggerHub APIライフサイクル統合の詳細はこちらをご覧ください。
設計プロセスをスケールする
既存の設計プロセスがある場合でも、API開発に「設計ファースト」のアプローチを始めたばかりの場合でも、SwaggerHubは、チームがAPI設計を標準化し、チーム間で共同作業し、OpenAPI/SwaggerでAPI設計ワークフローを集中化するのに役立ちます。SwaggerHubがチームの設計プロセスをスケールするのにどのように役立つかについて詳しく知りたいですか？デモをセットアップするために[email protected]にメールを送信するか、SwaggerHubチームのメンバーと連絡を取ってください。準備はできましたか？今すぐSwaggerHubの無料トライアルを開始してください。