API チームの間で、API デザインプロセスをより適切に標準化する傾向が強まっています。多くの企業にとって、API デザインを標準化する取り組みは、API の設計、開発、テストに関わる全員が共通の認識を持つための内部的な作業として始まります。
デザインガイドラインは、誰もが参照できるように PDF または社内 Wiki で公開され、チームがデザインガイドラインに従っていることを確認するためのプロセスが導入されます。しかし、多くの企業はこれをさらに一歩進め、API を使用する開発者や、彼らの経験から学びたい人々のためのリファレンスとして、これらのガイドラインを公開しています。Arnaud Lauret（API Handyman としてよく知られています）は、API Stylebook の作成者です。これは、API デザインを標準化するためのプロセスを効果的に実装した組織から学ぶことで、API 開発者がAPI デザインの課題を解決するのに役立つオンラインリソースです。Arnaud は、Cisco、Google、Paypal、Microsoft など、さまざまな業界の組織のスタイルガイドをレビューし、その調査結果を簡単にナビゲートできるリソースにまとめています。
最近、Arnaud 氏と API Stylebook がどのようにして誕生したのか、そして独自の API デザインガイドラインの設定を開始しようとしている組織への彼のアドバイスについて話す機会がありました。Arnaud 氏が説明するように、内部スタイルガイドラインを作成することは、プロセスのほんの始まりにすぎません。以下で全文インタビューを読んで、次に何が起こるか、そして Arnaud 氏が API Stylebook での彼の仕事から学んだ教訓を見つけてください。
API デザイナー向けのリソースとして API Stylebook を作成しようと思ったきっかけは何ですか？
基本的な API デザインの問題の解決策を見つけるのに非常に苦労したので、自分だけではないだろうと思い、API Stylebook を作成しました。REST API の設計を始めたとき、私の基本的な API デザインの問題の多くは簡単に解決できませんでした。同様の課題に直面した人々がそれらをどのように解決したかについての情報を見つけるのは困難でした。時には、質問への回答が見つからなかったこともありました。また、API を設計するときに考慮すべきすべての事項を認識していませんでした。
経験を積むにつれて、私は自分の答えを導き出しましたが、それは時には良く、時にはひどいものでした。また、いくつかの重要な側面を見落としていたことにも気づきました。いくつかの設計上の間違いを抱えて生活しなければならないことに加えて、最も困るのは、これらの間違いが業界で非常に一般的であるため、誰もがそれらを犯すべきではないということです。これらは何度も解決されてきた問題であり、誰もがそれらを再び解決するために時間を無駄にすべきではありません。私は人々が同じ間違いを犯したり、時間を無駄にしたりしないように何かをしたいと思いました。これが API Stylebook の始まりです。当時、ますます多くの企業や公共団体が、ガイドラインを公開することで API の設計方法を共有していることに気づきました。これらのガイドラインにはすべて、一般的な API デザインの問題への回答が含まれています。
私は単にリンクのリストを提供するという目的でそれらを収集し始めました。しかし、それらを読んでいるうちに、単にリンクのリストを提供するだけでは、デザイナーが解決策を迅速に見つけるのに本当に役立たないことに気づきました。それらはすべて、組織や使用されている語彙において非常に異なっているため、解決策を見つけるのは依然として本当に負担になる可能性があります。そこで、これらのガイドラインでカバーされているすべてのトピックをリストし、それらを正規化して、それらへの迅速かつ直接的なアクセスを提供することにしました。そして、API Stylebook が誕生しました。
API Stylebook で取り上げられているデザインガイドはどのように選ばれていますか？スタイルガイドを評価する際に探す特定の基準はありますか？
API デザインについて語るブログ記事は何千とあるかもしれませんが、私は実際に現実世界のシナリオで対峙した資料のみを提供したいと思っています。そのため、API Stylebook には企業で実際に使用されている「公式の API デザインガイドライン」のみを追加しています。
より多くの企業が API デザインの標準化に注力しているのはなぜだと思いますか？
企業がガイドラインを確立する最も明白な理由は、組織内で開発される API が増えれば増えるほど、それらの API が互いに一貫している必要があるからです。共通の動作、パターン、標準的な外観を共有する API を提供することで、社内外を問わず、それらを利用したい人々の作業が大幅に楽になります。もう一つの理由は、API デザインの効率性かもしれません。ガイドラインがあれば、API デザイナーは細かすぎる詳細について延々と議論したり、社内で既に解決済みのデザイン問題を解決しようとして時間を無駄にしたりする代わりに、本当に重要なことに集中できます。
OpenAPI については、よく講演したり書いたりされていることは承知しています。企業が OpenAPI のような標準を API 設計ガイドラインに組み込んでいるのをご覧になりますか？
私の意見では十分ではありません :-) API Stylebook で見つけたのは2つ（HaufeとZalando）だけです。しかし、Zalandoは間違いなくOpenAPIの利用方法の最良の例です。彼らは設計段階でOpenAPI仕様を使用し、バージョン管理システムに保存し、Zallyと呼ばれるカスタムツールでAPI設計を制御しています。これは素晴らしいです！OpenAPIと設計制御に関するより多くのツールが必要です。Zalandoは、OpenAPI仕様を使用してデータを正確に記述するためのヒントも提供しています。
ガバナンスとバージョン管理はよく話題になる2つのテーマです。組織が API スタイルガイドラインでガバナンスをどのように扱っているか、どのように見ていますか。
ガバナンスは、API を作成する理由から、その設計方法、ライフサイクルの管理方法まで、多くのトピックをカバーしています。API デザインガイドラインは、これらのトピックの一部をカバーするかもしれませんが、すべてをカバーするわけではありません。バージョン管理以外のガバナンスに関するトピックは、私が分析したガイドラインではあまり明確に示されていません。それらは主に API の設計方法に焦点を当てており、その他の側面についてはあまり触れていません。しかし、それでも、一部のガイドラインでは非推奨化 (Zalando や Atlassian) や API デザイン検証プロセス (Haufe) について言及しています。ガバナンスのガイドラインは、あまりにも異なる懸念事項を混同しないように、1つ以上の別のドキュメントで記述されるべきだと感じています。
バージョン管理は、間違いなくガバナンスのトピックであり、設計と密接に関連しており、ガイドラインにより多く記載されています。通常、API の特定のバージョンを呼び出す方法として提示されます。URL やコンテンツネゴシエーションなど、さまざまな戦略があります。しかし、API の 2 つのバージョンを区別する方法を知っていても、行っている変更が破壊的であるかどうかを知らないと意味がなく、これに関する情報を提供しているガイドラインはごくわずかです。
Googleはいくつかのヒントを提供していますが、やはりZalandoがこの主題に関して最も網羅的です。
API スタイルガイドラインの実装プロセスを開始する組織のために、他に何かアドバイスや、あなたの研究を通じて学んだ教訓はありますか？
ガイドラインを書けば仕事が終わったなどと考えるべきではありません。ガイドラインは進化しなければなりません。なぜなら、最初はすべての問題を網羅するわけではないからです。そして最も重要なことは、誰もがそれらを推進し、行われたことを管理しなければ、誰もガイドラインを読んだり尊重したりしないということです。API デザインガイドラインの「なぜ」と「どのように」について詳しく知りたい場合は、APIStrat に来て、私のセッション The Lord of API Designs に参加してください。
お読みいただきありがとうございます！API のリソースをもっとお探しですか？Swagger ニュースレターを購読してください。最高の API 記事、トレーニング、チュートリアルなどを毎月メールでお届けします。 購読する