APIをビジネスおよび戦略的イニシアチブの推進力として認識することは比較的最近の発展であり、組織は現在API戦略に多額の投資を開始しています。
API戦略の開発に多額の投資を行っている組織は、従来の技術リーダーを超えています。金融サービスから医療、教育から製造、その他多くの業界で、APIの採用が大幅に増加しています。
これに伴い、API記述形式の採用が爆発的に増加しています。たとえば、OpenAPI仕様（以前はSwagger仕様として知られていました）は、言語に依存せず人間が読めるAPIの契約を提供し、マシンと人間の両方がAPIが何をすべきかを解析して理解できるようにします。
今日、大小を問わず、数千の組織がOpenAPI仕様（OAS）を使用して、APIの開発を合理化し、採用を推進しています。組織の内部および外部API全体にOASを実装することは、特に多数の異なるチームにまたがる複数のAPIプロジェクトを拡張しようとする場合に、独特の一連の課題を伴います。
ここで、OASの実装を容易にするワークフローが役立ちます。
この電子書籍の目的は、組織内で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仕様（OAS）を入力
OpenAPI仕様（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コンシューマーのニーズに焦点を当てることができます。これにより、開発者中心のアプローチを採用し、時間や開発の他の側面を急ぐ前に、エンドコンシューマーに最適な方法で対応することができます。
- 独立性の実現：このアプローチにより、フロントエンドチームとバックエンドチーム、またはアーキテクト、テクニカルライター、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コードにアノテーションを追加することで、ランタイムまたはビルド時に既存のAPIからOAS定義を生成するために利用できるオープンソースツールがあります。
Swagger Inspectorのようなツールを利用することもできます。このツールを使用すると、任意のAPIリクエストをすばやく実行し、そのレスポンスを検証して、対応するOpenAPI定義を生成できます。Swagger Inspectorを使用して、各エンドポイントを呼び出し、関連するレスポンスを使用してOAS準拠のドキュメントを生成するか、一連の呼び出しをまとめて複数のAPIエンドポイントの完全なOASドキュメントを生成することにより、既存のREST APIのOASベースのドキュメントをすばやく生成できます。
OASを使用した大規模なAPI開発
ソフトウェア開発ライフサイクル、そしてAPIのライフサイクルにおいて、デザインを重要なステップとして受け入れる組織が増えていますが、大規模にAPIを効果的にデザインする方法を把握している組織はごくわずかです。
単一のチームで限られた数のサービスに取り組んでいる場合、デザインの管理は容易になり、PDF形式のガイドやWikiページに依存するだけで、全員の足並みを揃えるのに十分かもしれません。しかし、そのデザインプロセスを複数のチームや数百、さらには数千の異なるAPIにまで拡張する必要がある場合はどうなるでしょうか。
SwaggerHubでAPIワークフローを最適化する
API戦略を実装する際にチームが直面する最大の課題の1つは、さまざまなスキルセットと責任を持つさまざまなチームメンバーが、APIライフサイクルの適切な段階で関与することを確認することです。
その他の課題は次のとおりです。
- チーム管理とコラボレーション： OAS定義を更新し、APIの詳細なドキュメントを作成するために、チーム間でどのように連携しますか。
- バージョン管理：組織がAPIの設計とドキュメントを反復し続けるにつれて、APIの複数のバージョンを管理する複雑さが生じます。組織は、同じAPIの複数のバージョンをどのように効果的に管理しますか。
- OAS定義の安全なホスティングと共有： OASを使用してAPI戦略を拡張するにつれて、チームがOAS定義にアクセスするための集中リポジトリを維持することがますます重要になっています。チームは、APIライフサイクルのさまざまな側面を安全に調整する方法をどのように考えていますか。
- 既存のツールセットとの同期：特にソフトウェアとAPIの開発が、ソース管理ホスト、API管理プラットフォーム、テストスイートなど、さまざまな外部システムで行われている場合、APIのさまざまなバージョンで内部および外部環境をどのように最新の状態に保ちますか。
これらの課題に対処するには、組織が最適なAPI開発ワークフローを採用し、設計とドキュメントからテストとデプロイメントまで、APIライフサイクルのすべての段階でそのワークフローを最適化するために必要なツールを特定する必要があります。
私たちは、チームがAPIを設計および文書化するために連携する方法を変えるためにSwaggerHubを立ち上げました。昨年、私たちは数百人のSwaggerHubユーザーと話し合い、複数のチームにわたって、そして増え続けるAPIの数を考慮して、彼らがどのように設計プロセスを拡大してきたかをより深く理解しました。
CrowdFlowerのエンジニアリング担当副社長であるCameron Befus氏は、オープンソースのSwaggerツールから、よりスケーラブルなAPI設計のためにSwaggerHubに移行した経験を次のように説明しています。
「Crowdflowerはしばらくの間、APIを定義するためにSwaggerを使用してきましたが、SwaggerHubのおかげでそのプロセスが大幅に簡単になりました。新しいサービスを設計する際にコラボレーションを促進し、それらのサービスのドキュメント化と統合テストをはるかに簡単にするSwaggerやSwaggerHubのような優れたツールがあることは、私たちのチームにとって大きな助けになります。」
BonotelのCIOであるScot Hastings氏も、最近のAPIプロジェクトで新しい設計プロセスを開始した経験を共有しました。
「プロジェクトをさらに進めるにつれて、プロセスを高速化し、より効率的にする必要があることに気づきました。内部および外部のチーム間で、手間やコミュニケーションの問題なしに、ユーザーインターフェイスを自動生成し、コラボレーションを促進したいと考えていました… RESTful APIをより迅速に設計および開発する機能を提供することで、新しいサービスとサービスアップデートをより早く市場に投入できるようになります」とHastings氏は述べています。「これにより、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コンシューマーがモックに対してクライアントを開発できるようにすることができます。モックは、互換性があり、現実的なペイロードで応答することが保証されています。さらに重要なことに、「例」コンストラクトを使用して、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などのテストツールを含む、チームが信頼するツールとのシームレスな統合を提供しています。
SwaggerHubのAPIライフサイクル統合についてさらに詳しく知る。
SwaggerHubでワークフローを最適化する
SwaggerHubは、あらゆる規模のチームに対応できる柔軟なプランを提供します。すべてのOASアセットを一元的な場所に保存し、チームをセットアップおよび管理し、APIのライフサイクル全体でコラボレーションできます。クラウドで利用できるほか、エンタープライズソリューションを使用してお客様のファイアウォール内にインストールすることも可能です。
今すぐ始めましょう！SwaggerHubの14日間無料トライアルを開始するか、当社のエンタープライズソリューションの詳細については、チームに直接お問い合わせください。こちらでデモを予約できます。