ソフトウェア開発ライフサイクル、そしてAPIのライフサイクルにおいて、設計を重要なステップとして取り入れる組織が増えている一方で、APIを効果的に大規模に設計する方法を把握している組織はごくわずかです。
単一のチーム内で限られた数のサービスに取り組んでいる場合、設計の管理は容易であり、PDFスタイルのガイドやWikiページに頼ることで全員の認識を合わせるには十分かもしれません。しかし、その設計プロセスを複数のチームや数百、数千もの異なるAPIにわたって拡張する必要がある場合はどうなるでしょうか？
実際にスケールする設計プロセスの作成
私たちは、チームがAPIを設計・文書化するための共同作業の方法を変えるためにSwaggerHubを立ち上げました。この1年間で、私たちは何百人ものSwaggerHubユーザーと話し合い、彼らがどのようにして設計プロセスを複数のチームや増加するAPIにわたって拡張できたのかをより深く理解しました。
CrowdFlowerのエンジニアリングVPであるCameron Befus氏は、オープンソースのSwagger設計ツールからSwaggerHubへの移行が、API設計のスケーラビリティ向上にどのように役立ったかについて説明しています。
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設計プロセスをスケールしようとするときに直面する連携の課題と同様に、チーム全体の可視性を向上させるという困難な課題もあります。API設計の旅は、Swagger EditorやSwagger UIのようなオープンソースのSwaggerツールから始まることが多いです。これらのツールはAPIを効果的にモデル化および視覚化するために必要な機能を提供しますが、大規模なAPIチームの協力要件を促進するようには構築されていません。
OpenAPI を使用して API 設計を処理する場合、チーム全体がさまざまなサービスを設計するために行われている作業にアクセスできる一元的な場所を提供する必要があります。また、変更が発生したときに適切な人物に通知されるようにし、可視性を個別のメール、Slack メッセージ、GitHub チケットに限定しないようにする必要があります。
3. 依存関係の削減
API開発は、複雑なプロセスであるだけでなく、関係するチームにとって遅いプロセスになることもあります。チーム間の依存関係は、設計からコード生成、ドキュメント作成、テストケース作成に進もうとするチームの速度を低下させる最大の要因の1つとなりえます。チームが依存関係を減らして開発を高速化する方法の1つは、APIの「モック」または仮想化を利用することです。
SwaggerHubのAPI自動モック統合は、仕様で定義された静的応答を使用してAPIのモックを作成および維持します。SwaggerHubで新しいAPIを作成するときにモックを自動的に作成することも、後でいつでも手動で作成することもできます。モックは、開発者が実装する前に、APIを設計する際にテストするのに役立ちます。また、この統合により、バックエンドが準備される前にクライアントアプリケーション開発者は自分の部分の作業を開始できます。
コードを一行も書かずに、API消費者がモックに対してクライアントを開発することを可能にできます。このモックは、互換性があり、現実的なペイロードで応答することが保証されています。さらに重要なことに、モデル定義内で「example」構造を使用することで、OAS定義内でペイロードを直接調整できます。
4. 設計要件の設定と実施
企業のAPIへの投資は長期的な取り組みです。設計基準は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設計プラットフォームを構築し、その後、チームが優れたAPIを提供するために信頼するツール（Apigee、AWS、Microsoft Azure、IBM API ConnectなどのAPIゲートウェイ、Bitbucket、GitHub、GitLabなどのソース管理プラットフォーム、機能テスト用のSoapUIなどのテストツールを含む）へのシームレスな統合を提供しています。
SwaggerHub APIライフサイクル統合の詳細をご覧ください。
設計プロセスをスケールアップする
既存の設計プロセスがあるか、API開発への「デザインファースト」アプローチを始めたばかりかにかかわらず、SwaggerHubは、OpenAPI/Swaggerを使用して、チームがAPI設計を標準化し、チーム間で連携し、API設計ワークフローを一元化するのに役立ちます。
SwaggerHubを無料でお試しください！70,000人以上のAPI開発者、設計者、アーキテクト、CIOなどが、API設計プロセスをスケールするためにSwaggerHubを信頼している理由をご覧ください。
SwaggerHubの無料トライアルを今すぐ開始！.
質問がある場合、またはAPI設計プロセスの改善方法について詳しく知りたい場合は、SwaggerHubチームにご連絡ください: [email protected]