今日のハイパーコネクテッドな世界では、APIがますます重要性を増しており、ソフトウェアのあらゆる領域に浸透して、戦略的およびビジネスイニシアチブを推進するための新しく改善されたイノベーションを可能にしています。
近年、RESTful APIを構築および利用するための新しい手法が業界で急速に注目を集めており、MicrosoftとFacebookがその先頭に立っています。それがGraph APIです。最近、Microsoft GraphのPrincipal API ArchitectであるGareth Jones氏と話す機会があり、Graph APIとは何か、その開発につながった経緯、MicrosoftがAPI開発をどのように戦略化しているか、そしてGraph APIのような大規模なプロジェクトのバージョン管理に関する彼の考えについて理解を深めました。
Graph APIとは？
Microsoft Graph APIは、Microsoftクラウドサービスのデータと、それに関連するインサイトおよびインテリジェンスを1つのエンドポイントに統合する単一のエンドポイントです。
Microsoft Graph APIは、1年以上にわたって本番運用されており、Microsoft内の12以上の主要ビジネスグループと、そのサブサービスがGraphに接続されています。
Microsoft Graph開発スタック
出典: https://graph.microsoft.io/en-us/docs
Graph APIへの移行
MicrosoftのGraph APIは、まだ1年余りしか経っていません。Gareth氏の説明によると、Graphアーキテクチャへの移行は、主に顧客の問題を軽減するためでした。ご存じのとおり、Microsoftは膨大な組織であり、さまざまなクラウドベースのサービスを擁しており、それぞれが独自のAPIを持っています。そのため、エンドユーザーがこれほど多くのAPIを扱うのは少し困難でした。各サービスには、呼び出し方法、応答パケット、認証が異なっていました。そのため、これらのサービスを学習し、統合するために多くの時間とリソースが費やされていました。
Microsoftは内部でREST API設計標準を標準化しようとしましたが、さまざまなMicrosoftリソースにアクセスするための複数の認証の問題には対処できませんでした。Microsoft製品の相互接続性から、これらすべてのリソースをまとめることが最善の方法だと考えられました。さまざまなサービスとリソースの1つの接続されたグラフに変換することで、ユーザーは、常に統合方法を学ぶ必要もなく、APIトークンを再申請する必要もなく、サービス間をシームレスに移動できます。こうしてGraph APIが誕生しました。
「APIを1つの接続されたグラフに変換することで、ユーザーはサービス間を非常にシームレスに移動できます。私たちは、それらを単一のエンドポイントの下にまとめるだけでなく、実際にサービスを相互に接続し、情報グラフにリンクして、かなり簡単に横断できるという考えにすぐに興奮しました。」
Graph APIは新しいクラウドサービスを公開するものではなく、既存のサービスと接続するための新しい方法を提供します。Gareth氏が説明するように、Graphは、異なるエンティティとオブジェクト間を簡単にナビゲートし、異なるサービスからのデータと有意義な関係を形成することを可能にします。
Graphが顧客にとって意味するもの
Gareth氏によると、当初、人々はGraph APIの概念について、実際に使用する前に魅了されると同時に少し懸念も抱いていました。しかし、さまざまなサービスとの往復、学習、統合にかかる時間を節約できるという能力は、APIの最初の顧客にとって大きな喜びの源でした。人々は、実際に実装を見て試す機会を得るまでは、当然のことながら心配していました。
当初、ユーザーが提起した懸念の1つは、ユーザーと利用したいサービスの間に「余分な層のホップ」が追加されることでした。これはパフォーマンスと読み込み時間に悪影響を与える可能性があります。しかし、実際には、そのようなプロキシコールとルーティングを非常に迅速に行うことができることが分かりました。これはミリ秒単位で発生し、これらの懸念はすぐに解消されました。
「私たちは、これらの懸念は、複数のサービス間で複数回の往復を行ったり、新しいAPI呼び出しを学習するために膨大なリソースを費やしたりすることに比べれば、それほど大きな問題ではないことを人々に非常に迅速に示すことができました。」
API分野で働く上で最も良い点の1つは、さまざまなユーザーが創造的な方法でAPIと統合するのを見て、嬉しい驚きと喜びを感じることだとGareth氏は言います。Graphの特にGareth氏を驚かせた側面は、教育分野がGraphを熱心に採用したことでした。大学や幼稚園から高校までの教育機関はGraphから多くの恩恵を受け、通常予想されていた以上の普及率を達成しました。
API構築へのアプローチ
マイクロソフトには複数のAPIに取り組む様々なチームがあり、そのためAPIに関する集中型開発ポリシーはありません。このような大規模な組織において、彼らがAPI構築にどのようなアプローチを取ったのか（デザインファーストかコードファーストか）を知りたいと私は切望していました。
Gareth氏によると、マイクロソフトは文化的に、各チームが自身の開発ワークフローに合致すると考えるあらゆるアプローチを採用する柔軟性を与えていました。彼は、OneDriveチームが採用している「ドキュメンテーションファースト」アプローチの例を挙げました。これは「デザインファースト」の極端な例です。「デザインファースト」アプローチでは、コードを書く前に個々のAPIの設計に焦点を当てます。設計は、OpenAPI仕様やその他の記述言語で書かれた、コードのレベルにまで詳細化された、人間と機械が読み取れる一種の参照ドキュメントです。「ドキュメンテーションファースト」アプローチでは、開発プロセスはシナリオドキュメンテーションから始まります。なぜなら、高レベルで顧客中心のユースケースシナリオこそが優れたAPIを生み出すからです。
「デザインファーストの提唱者は、個々のAPIの設計について、個々のAPIコードのレベルまで語る傾向があります。OneDriveチームが実際に観察したのは、優れたAPIを生み出すのは包括的なシナリオであるということです。顧客は一連のAPIを使って実際に仕事を成し遂げようとしており、シナリオドキュメンテーションはこれらの特定のタスクを最善の方法で実行する方法を参照しています。その後、彼らはそのドキュメントに注釈を付け、各APIのAPI記述言語ドキュメントを生成できるようにします。彼らのAPI記述言語はドキュメンテーションから生まれるのであり、逆ではありません。」
しかし、Gareth氏が以前指摘したように、このアプローチは集中化されておらず、一部のチームのみがこれに従っています。Gareth氏は、API記述言語がGraph APIを設計するまで完全に進化していないため、Design FirstまたはDocumentation Firstのアプローチは、本番環境のAPIにリリースされる破壊的変更の数が限られており、長期間にわたって発生するため、通常はアジャイルプロセスではないAPI開発プロセスには優れていると考えています。そうは言っても、Graph APIを開発するためのこのアプローチには限界があります。Swagger 2.0はリソースと操作を記述するには優れていましたが、Graphの相互接続された性質は、Swagger 2.0で完全に記述することを不可能にします。Microsoftは、Graphの記述をはるかに容易にするOAS/Swagger 3.0の追加に非常に期待しています。
結局のところ、さまざまな開発方法論に適応するには特定のレベルのスキルが必要であり、それはチームの強みと成熟度に大きく依存します。このような柔軟な方法論の使用は、Swaggerに関するあらゆることを統合した開発プラットフォームであるSwaggerHubの核心的な原則でもあります。SwaggerHubは、組織やチームが、設計、ドキュメンテーション、デプロイなど、APIライフサイクルのあらゆる側面を活用するために、自身のスキルセットに最適なワークフローに従うことを可能にします。
バージョン管理戦略
Graphの下にこれほど多くのサービスが統合され、かなりのユーザーベースがあるにもかかわらず、Microsoftはバージョン1にとどまっています。
Gareth氏は、Graph APIには、破壊的変更を防ぎつつ、さまざまなユニットが無制限の非破壊的変更を追加できるようにする厳格なバージョン管理ポリシーがあると説明しています。このポリシーは非常に堅牢であることが証明されており、そのためチームはバージョン全体を更新する必要がありませんでした。将来的には、間違いなくAPIのメジャーアップデートがあり、Graph APIの新しいバージョンがリリースされることになります。Gareth氏は、グラフを構築するためにさまざまなチームと協力することを「同期されたダンス」に例えました。バージョン管理に関するGareth氏の推奨事項は、常に顧客を念頭に置くことです。新しいバージョンがリリースされた場合でも、Graph APIのV1は顧客がV2に徐々に移行できるように、長期間にわたって利用可能になるとGareth氏は言います。
「APIサービスと、私たちがAPIサービスと結ぶその契約は、すべて信頼に関するものです。開発者への共感は私たちにとって本当に重要です。Microsoftが従うモットーは、開発者にとって素晴らしい製品を構築し、この開発者の信頼を獲得し維持するために必要なあらゆることを行うことです。」
Gareth氏は、効果的なコミュニケーションが、最終顧客との良好で信頼できる関係を維持するための鍵であると信じています。
「適切なテレメトリーが導入されていれば、どの顧客が古いAPIをまだ使用しているかを把握できます。そうした顧客に連絡を取り、彼らを前進させるために何ができるか、適切なタイムラインでアップグレードの道のりをどのように進め、協力できるかについて、良好な会話をすることができます。」
まとめ
MicrosoftのGraph APIはCommon Schema Definition Language (CSDL) を使用しています。Gareth氏は、次期バージョンの仕様に付属する新機能によってGraph APIを仕様で設計できるため、OpenAPI Specification (OAS) 3.0に期待していると述べています。Graph APIがOAS 3.0をどのように取り入れて進化するのか、そしてGareth氏が来年どのような新しい革新と成功事例を語ってくれるのか、注目に値します。
お読みいただきありがとうございます！APIリソースをもっとお探しですか？Swaggerニュースレターを購読してください。毎月、最高のAPI記事、トレーニング、チュートリアルなどをお届けします。 購読する