APIがビジネスおよび戦略的イニシアティブの原動力であるという認識は、かなり最近の進展であり、組織は現在、API戦略に多額の投資を始めています。
API戦略の開発に多大な投資を行っている組織は、従来のテクノロジーリーダーを超えています。金融サービスからヘルスケア、教育から製造業まで、そしてその他多くの産業で、APIの採用が大幅に増加しています。
これに伴い、OpenAPI Specification（旧称Swagger Specification）のようなAPI記述フォーマットの採用が爆発的に増加しました。これは、APIの契約を言語にとらわれず人間が読める形式で提供し、マシンと人間の両方がAPIの動作を解析し理解できるようにします。
現在、大小数千の組織がOpenAPI Specification（OAS）を利用して、APIの開発を合理化し、採用を促進しています。組織の内部および外部API全体にOASを実装することは、特に多数の異なるチーム間で複数のAPIプロジェクトをスケールアップしようとするときに、独自の課題をもたらします。
ここで、OASの実装を促進するワークフローが役立ちます。
このeBookの目的は、組織内でOASを扱うためのわかりやすいワークフローを紹介することです。
APIプラットフォームへの変革
アプリケーションプログラミングインターフェース、つまりAPIは、PCが発明されるずっと前から存在し、常に技術資産として見られていました。しかし、この10年間で、インターネット、ソーシャルメディア、eコマース、モバイルデバイスによって引き起こされた情報の混乱は、より多くの組織に、データとサービスの流通チャネルとしてのAPIの重要性を理解させました。
今日、公開APIの数は約50,000と推定されています。これには、世界中の主要産業で採用が増え続けている何千ものプライベート管理された内部APIは含まれていません。SmartBearの2016年APIレポートによると、APIプロバイダーの5人に1人が過去5年以内にAPIの開発を始めたばかりです。
接続デバイス数の指数関数的な増加に伴い、APIの採用は増加する一方です。IoT革命もまた到来しており、家庭用デバイス、ボット、ウェアラブルデバイスすべてが、常時接続したいという私たちの高まる欲求に貢献しています。2020年までに、世界中のすべての人が平均で7台のデバイスを所有すると推定されています。
これは、組織がAPI戦略について考え始めるべきであることのさらなる証拠です。なぜなら、APIはこれらすべての異なるプラットフォームやデバイスに浸透するための最良の方法だからです。
OAS駆動型開発の紹介
APIは明らかにビジネス成長を促進する方向へと進んでいます。APIを活用したい企業は、サードパーティ開発者による最小限の労力で、優れたセルフサービス消費を考慮する必要があります。以前は、APIは多くの人々によって使用されることを意図していませんでした。APIはデータ駆動型であり、接続と通信のいくつかの特殊なユースケースを解決することを意図していました。ドキュメントは最小限であるか、まったくなく、使用される正規形はコアデータベースから直接専門用語に従っていたため、少数のネットワークの人々以外は誰もそれらを理解できませんでした。
言うまでもなく、過去のAPIはセルフサービス消費を意図していませんでした。上記のことは、現代のWeb APIにはもはや当てはまりません。新しい時代のREST APIは、その前身とは異なり、データ駆動型ではなく、より消費者駆動型です。真の消費者問題を解決する優れた設計のAPIが重要であり、Dropbox、Stripe、eBayのような企業からのAPIにこの焦点が見られます。HTTP標準に基づいた再利用可能なインターフェースは、消費者からの要求とセルフサービスのために構築され、データと機能の再利用を可能にする多くの企業によって現在必要とされています。
OpenAPI Specification (OAS) の登場
OpenAPI Specification (OAS) は、RESTにとってWSDLがSOAPであったものと同じです。これは、設計者、開発者、テスター、DevOpsがAPIを構築し維持するための共通のフレームワークを提供します。この仕様は、REST APIを構築および実装するためのルールのセットと考えてください。
OASは言語に依存せず、人間にも機械にも読みやすい形式です。これにより、ソースコード、追加のドキュメント、またはネットワークトラフィックの検査を必要とせずに、人々もコンピュータもサービスの機能を検出して理解することができます。例えば、OAS定義から直接、インタラクティブで美しいAPIドキュメントを自動生成する機能などが挙げられます。
インタラクティブなドキュメントは、Swagger UIと呼ばれる独自のツールへと進化しました。Swagger UIは、開発チームとエンドユーザーの両方が、APIを自社のアプリケーションに手動で統合・実装することなく、APIのリソースを視覚化し、操作できるようにします。
APIにOASを追加する利点
- API設計とコラボレーションのための適切なキャンバス: OASは、コーディングを開始する前に、チームがAPIの設計について共同作業するための単一の焦点を提供します。
- 整合性を保ちつつ再利用するための明確かつ正式なメカニズム: OAS定義内部には、共通のオブジェクト間で再利用および参照するために明確に設定されたメカニズムがあります。これらは、定義を作成した人がその意味を説明する必要がありません。
- 自動化のための適切なツール: OASは、従来のサーバーテンプレートまたはサーバーレスサーバーテンプレートの生成に適した構造とツールを提供します。サーバーテンプレート以外にも、ほぼすべての一般的なクライアント言語でクライアントSDKの生成をサポートしています。
- テスト自動化と監視強化に必要な情報: QAチームはOAS定義をテストソリューションにインポートでき、APIの操作を理解するのに伴う推測作業を減らすことができます。
APIライフサイクルにおけるOASの役割
今日の競争が激しく相互接続されたビジネス環境で成功するためには、組織はAPIプログラムを一流の扱いとし、開発者が進化し続ける内部および外部環境と、選択したワークフローで柔軟に統合できるようにする必要があります。
これが、APIライフサイクル管理に適したツールを選択することが重要になる大きな理由です。ほとんどのチームにとって、OASを使用したAPIライフサイクルは次のようになります。
OAS駆動型アプローチの利点
OAS駆動型API開発では、他のライフサイクル操作が実装される前に、APIの定義を最初に設計することを提唱しています。これは、APIのビジネスロジックを構築する前、APIのエラーや欠陥をテストする前、またはその他のライフサイクル機能を行う前に、APIのエンドポイントが示す正確なリクエストとレスポンスを詳細に記述したAPIインターフェースを設計することを意味します。
OAS駆動型アプローチは、API開発における消費者中心のアプローチに直接関連するいくつかの大きな利点をもたらします。
- より良い開発者体験 (DX): API消費における良い開発者体験は、競争の激しいAPIエコシステムにおいて非常に重要です。事前にAPI消費者のニーズに焦点を当てることができます。これにより、開発者中心のアプローチを採用し、開発の時間やその他の側面を競う前に、エンド消費者に最適な方法で対応できるようになります。
- 独立性を可能にする: このアプローチにより、フロントエンドチームとバックエンドチーム、アーキテクト、テクニカルライター、QAなど、APIに取り組むさまざまなチーム間の依存関係が軽減されます。これは、APIの定義が、APIが何をすべきか、そしてそれが彼らの職務機能にどのように関連するかについて、さまざまな関係者を調整し続けるためです。それは、APIの意図されたサービスとその機能の間の契約として機能し、それらの間のコミュニケーションを容易にします。
- 市場投入までの期間短縮: 依存関係が解消されるため、異なるチームがそれぞれの機能をはるかに速く、効率的に実行できます。チーム間の引き継ぎプロセスが大幅に簡素化され、APIのリリース速度が大幅に向上します。
- 外部の人がAPIを理解するのを助ける: APIを最初に設計することは、理解しやすく使いやすい消費者向けのAPIを構築するための強制機能として機能します。これにより、テクニカルライティングチームも、適切に設計されたAPIから素晴らしいドキュメントを作成できるようになります。
- APIのテストを作成する: OAS定義は、誰かがAPIを呼び出したときにレスポンスがどのように見えるかを記述する契約を提供します。この契約は、テストケースを作成するために再利用できます。これにより、APIをテストするために必要なセットアップチームの時間を大幅に削減できます。API定義をインポートすることで、機能テスト、ロードテストを作成できます。
- 実装コードとSDKを生成する: ドキュメントの生成に加えて、OpenAPI定義は、実装コードとSDKを作成することで開発を加速するために使用できます。API定義ファイルは、Swagger CodegenやSwaggerHubなど、さまざまなツールにインポートできます。これらのツールは、Java、Scala、Rubyなど、さまざまな言語でコードを作成します。
- APIを公開する: Amazon API Gateway、Azure、Apigee、Google CloudなどのAPIゲートウェイはすべて、API定義を受け入れてライブAPIを作成します。
- APIを監視する: 理想的には、顧客が気付く前にAPIに問題があるかどうかを知りたいものです。定義をAlertsiteのようなツールにインポートすると、APIを自動的に監視できます。
多くの組織にとって、OpenAPI駆動型アプローチ（「デザインファーストアプローチ」とも呼ばれる）への完全な移行は、一夜にして実現できるものではありません。場合によっては、チームは依然としてコードファーストアプローチに従っています。このアプローチでは、すでに構築され、すでにデプロイされている既存のAPIに対してOAS定義が生成されます。コードファーストアプローチは、ビジネス要件が設定された後にコード開発が行われ、最終的にコードからドキュメントが生成される、より伝統的なAPI構築方法です。
開発者は要件ドキュメントから直接APIのコーディングを開始すれば、APIをはるかに迅速に実装できます。これは、市場投入戦略がAPIプログラムの成功において速度と俊敏性を重要な要素として強調している場合に重要です。コードファーストアプローチでは自動化がはるかに容易であるという事実がこのケースを強化するのに役立ち、多くのライブラリがスキャフォールディングサーバーコード、機能テスト、デプロイメント自動化をサポートしています。APIコードに注釈を追加することで、実行時またはビルド時に既存のAPIからOAS定義を生成するために活用できるオープンソースツールがあります。
Swagger Inspectorのようなツールを活用することもできます。これは、任意のAPIリクエストを迅速に実行し、そのレスポンスを検証し、対応するOpenAPI定義を生成できます。Swagger Inspectorを使用して、各エンドポイントを呼び出し、関連するレスポンスを使用してOAS準拠のドキュメントを生成するか、一連の呼び出しを連結して複数のAPIエンドポイントの完全なOASドキュメントを生成することで、既存のREST APIのOASベースのドキュメントを迅速に生成します。
大規模なOASでのAPI開発
ソフトウェア開発ライフサイクルとAPIのライフサイクルにおいて、デザインを重要なステップとして捉える組織が増えていますが、APIを効果的に大規模に設計する方法を把握している組織はごくわずかです。
1つのチームで限られた数のサービスに取り組んでいる場合、デザインは管理しやすく、PDFスタイルガイドやWikiページに頼るだけで全員の足並みを揃えることができるかもしれません。しかし、そのデザインプロセスが複数のチームや数百、あるいは数千もの異なるAPIにスケールする必要がある場合はどうなるでしょうか？
SwaggerHubでAPIワークフローを最適化
API戦略を実装する際にチームが直面する最大の課題の1つは、さまざまなスキルセットと責任を持つチームメンバーがAPIライフサイクルの適切な段階で関与することを確実にすることです。
その他の課題は次のとおりです。
- チーム管理とコラボレーション: チーム間で連携してOAS定義を更新し、APIの詳細なドキュメントを作成するにはどうすればよいでしょうか？
- バージョン管理: 組織がAPIのデザインとドキュメントを継続的に反復するにつれて、APIの複数のバージョンを管理する複雑さが発生します。組織は同じAPIの複数のバージョンを効果的に管理するにはどうすればよいでしょうか？
- OAS定義のセキュアなホスティングと共有: OASでAPI戦略をスケールアップするにつれて、チームがOAS定義にアクセスするための集中リポジトリを維持することがますます重要になります。チームはAPIライフサイクルのさまざまな側面をセキュアに調整することについてどのように考えるべきでしょうか？
- 既存のツールセットとの同期: 特に、ソフトウェア開発とAPI開発がSource Control Hosts、API Managementプラットフォーム、テストスイートなどのさまざまな外部システムで行われている場合、APIの異なるバージョンで内部および外部環境をどのように最新の状態に保つことができますか？
これらの課題に対処するには、組織は最適なAPI開発ワークフローを採用し、APIライフサイクルのすべての段階（設計からドキュメント、テスト、デプロイまで）でそのワークフローを最適化するために必要なツールを特定する必要があります。
私たちは、チームがAPIの設計とドキュメント作成の共同作業の方法を変えるために、SwaggerHubを立ち上げました。過去1年間、私たちは何百人ものSwaggerHubユーザーと話をして、彼らがどのようにデザインプロセスを複数のチームと増加するAPIに拡張したかをよりよく理解しました。
CrowdFlowerのエンジニアリング担当VPであるCameron Befus氏が、よりスケーラブルなAPI設計のためにオープンソースのSwaggerツールからSwaggerHubに移行した経験について説明しています。
「Crowdflowerは以前からSwaggerを使ってAPIを定義してきましたが、SwaggerHubのおかげでそのプロセスは格段に楽になりました。新しいサービスを設計する際にコラボレーションを促進し、それらのサービスのドキュメント作成と統合テストをはるかに容易にするSwaggerやSwaggerHubのような優れたツールは、私たちのチームにとって非常に大きな助けとなっています。」
BonotelのCIOであるScot Hastings氏も、最近のAPIプロジェクトで新しいデザインプロセスを立ち上げた経験を共有しています。
「プロジェクトを進めるにつれて、プロセスを加速し、効率を高める必要があることに気づきました。ユーザーインターフェースを自動生成し、内部チームと外部チーム間のコラボレーションを煩雑さやコミュニケーションの問題なく促進したかったのです... RESTful APIをより速く設計・開発できるようになったことで、新しいサービスやサービスアップデートをより早く市場に投入できるようになりました」とヘイスティングス氏は言います。「それがSwaggerHubが私たちのソフトウェア開発ライフサイクルにおいて重要な要素である理由です。」
CrowdFlowerやBonotelのような組織は、API設計にOpenAPIを標準化し、APIワークフローにシームレスに適合し、SwaggerHubでAPI設計についてより効果的に共同作業できるツールを採用することで、API設計を拡大することができました。
そして、彼らはまた、API設計プロセスを成功裏に拡大したチームから私たちが目にしたいくつかの主要な原則を代表しています。
デザインプロセスを拡大する準備はできていますか？以下に、取るべきいくつかの重要な手順を示します。
1. チームを連携させる
優れたAPI設計は、API開発ライフサイクルに関わるすべてのステークホルダー間の効果的な調整に依存します。デザイン要件についてチームが連携していない場合、または適切な人々が必要なデザイン変更の可視性を得られない場合、少数のAPIを超えてスケールしようとすると摩擦が生じます。組織がデザインプロセスについてチームメンバーを連携させようとする一般的な方法の1つは、ConfluenceやGitHubなどのコラボレーションツールを使用することです。
しかし、これらのツールはソフトウェア開発ライフサイクルにおいて重要な役割を果たす一方で、API設計ワークフローの管理という特定のユースケースに対しては設定が複雑になる場合があります。
SwaggerHubでは、組織を作成し、チームメンバーを招待してAPIの設計とドキュメント作成に共同作業することができます。各組織は、APIライフサイクルにおける役割に応じて複数のチームを持つことができます。組織の所有者は、設計プロセスへの関与に基づいて、チームメンバーに役割を割り当て、アクセスを管理できます。SwaggerHubでのコラボレーションについて詳しくはこちらをご覧ください。
2. 設計プロセスの可視性の向上
チームがAPI設計プロセスを拡大しようとするときに直面する連携の課題と同様に、チーム全体での可視性を向上させるという困難な課題もあります。多くの場合、チームはSwagger EditorやSwagger UIのようなオープンソースのSwaggerツールからAPI設計の旅を始めます。
そして、これらのツールはAPIを効果的にモデル化し、視覚化するために必要な機能を提供しますが、大規模なAPIチームの共同作業要件を促進するようには作られていません。OpenAPIを使用してAPI設計を処理している場合は、チーム全体がさまざまなサービスの設計で行われている作業にアクセスできる中央の場所を提供する必要があります。また、変更が発生したときに適切な人々に通知が届くようにし、可視性を個別の電子メール、Slackメッセージ、GitHubチケットに限定しないようにする必要があります。
3. 依存関係の削減
チーム間の依存関係は、コードの生成、ドキュメントの作成、テストケースの作成という設計以外の作業に進みたいチームの速度を低下させる最大の要因の1つとなり得ます。チームが依存関係を減らし、開発を加速できる方法の1つは、APIの「モック化」または仮想化です。SwaggerHubで新しいAPIを作成する際に自動的にモックを作成することもできますし、後で手動で作成することもできます。
モックは、開発者が実装する前に、APIを設計する際にテストするのに役立ちます。また、この統合により、クライアントアプリケーション開発者は、バックエンドが準備できる前でも自分の部分に取り組み始めることができます。コードを1行も書かずに、APIコンシューマーがモックに対してクライアントを開発できるようにし、互換性のある現実的なペイロードで応答することが保証されます。さらに重要なのは、「example」構造を使用することで、OAS定義内でペイロードを直接調整できることです。SwaggerHubでのモックについて詳しくはこちらをご覧ください。
4. 設計要件の設定と実施
企業のAPIへの投資は長期的な取り組みです。設計標準はAPIの実装を改善するだけでなく、APIの更新方法や新しいAPIの開発方法も決定します。設計ガイドラインが設定されると、それを基盤としてAPIを開発し、組織が設計および開発プロセスをスケールできるようになります。設計はクライアントとサービスがどのようにやり取りするかを定義するため、設計に違いがあると、サービスの開発段階で混乱とオーバーヘッドが生じます。これらの不整合は増殖するばかりで、その影響はAPIライフサイクル全体に拡大します。
SwaggerHubが設計の一貫性の問題に対処する方法の1つは、組み込みのスタイルバリデーターで、API定義が特定の記述標準と一致するかどうかを確認することです。たとえば、会社のガイドラインでは、すべてのプロパティに例が指定されている必要がある場合があります。スタイルバリデーターは、そのようなチェックを自動化するのに役立ちます。SwaggerHubでの設計の標準化について詳しくはこちらをご覧ください。
5. 設計における再利用性の向上
SwaggerツールやOASを使用してAPIを定義しているAPIチームからよく聞くことの1つは、何百ものAPIにわたって複数のエンドポイントを定義する際に、設計プロセスが非常に退屈になる可能性があるということです。すべてのエンドポイントを個別に繰り返し定義する必要があるため、設計プロセスが遅くなり、API設計に矛盾が生じる可能性があります。
そのため、SwaggerHubは設計プロセスにドメインの概念を導入しました。ドメインは、複数のAPIや他のドメイン間で共有できる再利用可能なコンポーネントです。ドメインには、定義、パスアイテム、パラメーター、レスポンスなどのコンポーネントを含めることができます。SwaggerHubでの設計の再利用について詳しくはこちらをご覧ください。
6. 信頼するツールとの統合
設計からAPIのドキュメント作成、構築、デプロイメントまで迅速に移行できることは、スケーリング可能なAPI設計プロセスを確立するために不可欠です。最高の設計標準であっても、最初のフェーズを超えて移行を開始するときに摩擦が生じると、API設計をスケーリングするのに役立ちません。APIベンダーがこの問題に対処しようとした方法の1つは、API管理をより重視するツールの上に、追加の設計機能を構築することでした。オールインワンソリューションがあることは素晴らしいことですが、新しいツールを導入したいときに柔軟性がなく、組織を単一のソリューションにロックインすることも必要になります。
SwaggerHubでは、異なるアプローチを採用しました。チームがAPI設計プロセスの「信頼できる情報源」として使用できる、世界クラスのAPI設計プラットフォームを構築し、その後、Apigee、AWS、Microsoft Azure、IBM API ConnectなどのAPIゲートウェイ、Bitbucket、GitHub、GitLabなどのソース管理プラットフォーム、および機能テスト用のSoapUIなどのテストツールを含む、優れたAPIを提供するためにチームが信頼するツールとのシームレスな統合を提供しています。
SwaggerHub APIライフサイクル統合について詳しくはこちらをご覧ください。
SwaggerHubでワークフローを最適化
SwaggerHubは、あらゆる規模のチーム向けに柔軟なプランを提供しています。すべてのOASアセットを一元管理し、チームを設定して管理し、APIのライフサイクル全体で共同作業を行います。クラウド版またはエンタープライズソリューションとしてファイアウォール内にインストールできます。
今すぐ始めましょう！ SwaggerHubの14日間無料トライアルを開始するか、エンタープライズソリューションについて詳しく知りたい場合は直接チームに連絡して、こちらからデモをスケジュールしてください。