APIデザインレビューは死んだ。APIデザインレビュー万歳!

いいね

スケールの大きなAPIをデザインする過程では、一貫性を生み出すために 計画的な努力が必要だ。多くのAPIと真のプラットフォームのように感じられるものとの主な違いは、一貫性である。この場合の一貫性とは、複数のAPIを使用する場合、命名規則、ページングなどのインタラクション・パターン、認証メカニズムなどの要素が例外なく標準的であることを意味する。

これまでレビュー委員会は、開発が完了したと思われたときに、遅延を誘発する発見によってAPI開発者にトラウマを与えてきた。さらに悪いことに、委員会に設計が引き継がれ、進捗を停滞させたり、問題点を避けるための抜け道を開発者に見つけることを促したりする。

最新のプラットフォームを最大限活用するためには、分散型ガバナンスによる実現化が、より拡張性があり魅力的なアプローチとなる。これは単純に、各ドメインや機能エリアに、API開発者のためのガイドとなる標準や全体的なアーキテクチャについて教育を受けた専門家がいることを意味する。

さらに重要なことは、開発の大部分が完了する前にAPI設計に合意することである。これにより納期を危うくするような土壇場での発見(しばしばデザイン・ファースト・アプローチと呼ばれる)をほぼ避けることができる。OpenAPI(HTTP/"REST "APIのデファクトスタンダード)のような仕様フォーマットに従うことで、開発前にAPIを定義できる。これにより、より早い段階での調整と問題の特定が可能になる。

このような背景を念頭に置き、長期化するタイムラインや開発者の関与不足を避けるために、どのようにプロセスを開発し、組織を準備して、API設計レビューを実施するのか詳しく見ていこう。

ここでは、円滑なプロセスを確保するための重要な前提条件をいくつか紹介する。

1. 一貫した言語/用語を定義する

APIの使用は経験則に大きく依存するものであり、そのため言語の影響は他のほとんどの設計領域よりも不釣り合いに高い。チームメンバーそれぞれが様々な用語の定義や説明の仕方を微妙に変えている可能性があり、それがAPIチームの混乱や生産性の低下に現れている。

APIポータル/ドキュメンテーションは優れた開発者エクスペリエンスに不可欠だが、よくデザインされたAPIは、あまり考えなくても理解できるはずだ。もし用語がなじみがあるもので、インタラクションのパターンが明らかであれば、利用者の活用に大きな問題は起きない。この一貫性は、たくさんのAPI群ではなく、1つのプラットフォームのように感じられる要因となる。

APIプログラムとガバナンス・プロセスを確立する際には、共通の言語から始める。最初は不可能に思えるかもしれないが、顧客中心の共有語彙/文法をプラットフォーム用に定義することは不可欠であり、組織全体で理解が促進される。多くの用語は企業内で様々な意味を持ち、さらに悪いことに、最終利用者が認識できない用語であることも多い。

事前にこの課題に対処することで、APIを設計している最中にネーミングをめぐる問題を避けることができる。関係するステークホルダーと各領域について検討し、共有される用語を定義すると、API設計者が広く利用でき、認識できるようになる。そして、社内の用語の標準化が決まったら、それが社外のニーズにも適合しているかどうかをチェックすることを忘れてはならない。顧客言語を使用し、API開発に顧客中心の視点を持つことは、チームが馴染みのない専門用語で顧客を混乱させることを避けるのに役立つ。これにより内部的な理解と外部的な理解が一致していることを確認できる。

2. 共有コンポーネントの定義

API利用者がAPI間で異なるモデルやパラメータに遭遇すると、混乱し、フラストレーションが溜まり、時間のかかるプロセスになりかねない。例えば、連絡先情報を参照するAPIを使用していて、同じプラットフォームの次のAPIが全く異なるモデルを使用している場合、利用者はしばしばこれらの違いを解決しなければならない。さらに悪いことに、このデータの取り扱いにおけるシステム的な違いが展開され、機能的な違いを生み出すこともある。

できるだけ早い段階で、共通のコンポーネント(モデル、パラメータ、ヘッダーなど)とそれをサポートするシステムを特定する。API定義で共有コンポーネントにリンクすることで、それらのコンポーネントへの将来の変更がプラットフォーム全体で展開しやすくなり、API利用者の過度な認識負担も軽減される。

共通のコンポーネントが多ければ多いほど、一貫性の向上、再利用性、更なるコラボレーションの機会、効率性の向上が期待できる。私たち開発者は皆、"DRYメソッド"Don't Repeat Yourself(同じことを繰り返すな)が大好きだ。共有コンポーネントが多ければ多いほど、同じものを何度もゼロから作る必要がなく、イノベーションを起こしやすくなる。共有コンポーネントはまた、チームを素早くスケールさせ、新しい開発者やAPIチーム以外の関係者を簡単にトレーニング可能にする。

3. 共有スタイルガイドとリンティングルールの適用

単純な命名規則、インタラクションパターン、認証メカニズムの大部分については、スタイルガイドによる自動化を提供することで、可能な限り早い段階で不整合にフラグを立てることができる。

最初のスタイルガイドは2013年から2015年にかけて作成され、API開発チームに対するルック&フィール(別名DX)の期待値を設定した。デザインの一貫性の必要性はAPIプラットフォーム開発の初期から明らかであり、Paypal(実は私もこのチームの一員だった!)とHerokuによる初期の努力の結果、成功したプログラムから最初のスタイルガイドが公開された。

スタイルガイドに役立つ様々な自動化ツールがある一方で、オープンソースのツールSpectralはAPI リンティングルールセットを定義するための標準として登場した。パスやパラメータなどの規約を前もって揃えておき、自動化された構文チェックルールを定義することで、どの規約が"正しい"かをめぐる議論による遅延を避けることができる。一度議論し、ルールを定義してしまえば、もう二度と議論する必要はない!構文エラーをなくすのだ。

自動化できない 設計基準については、文書化し、API設計者が簡単に利用できるようにすべきである。自動化されたルールと手動で検証されたルールの重要性を説明するトレーニングを行うことで、開発者のモチベーションを高め、独創性が高まり、予想外な事象や不要な摩擦を避けることができる。

4. 組織全体にAPI設計レビュアーを配置する

APIイネーブルメントチームはこれらのデザインスタンダードを管理し、コミュニティを育成するために存在すべきであるが、各機能エリアやドメインで権限を持たせるべきである。

API標準は重要だが、システム上の制約、特定の顧客のニーズ、組織の強みと弱みなどのそれぞれの領域に関する知識は、その世界の一員である専門家が扱うのがベストだ。もし中央集権的なAPIイネーブルメントチームメンバーが社内の全てを知ることを期待されるなら、納期の遅れや開発者の離反につながるボトルネックとなることはほぼ確実だ。

トレーニングワークショップは、API標準の重要性を広く認識させるための強力な手法となる。さらに、ガバナンスを提供する権限を持つ適切なSMEを発見することもあるだろう。APIへの情熱を表し(私はよくこれらを "反逆者のバンド "と呼ぶ)、一貫性と標準の関連性に対する認識を示し、仲間やレポートから技術的に尊敬されている人物を探すのだ。

成功するAPIの開発には、対照的なスキルセットを持つ組織全体の多くの人々が関わることになる。APIを構築しデプロイする人、APIの価値を見極めビジネス上の問題の戦略面に携わる人などである。デザインレビューに誰を参加させるかについては、ビジネス利害関係者のことも忘れないでほしい。技術的な側面しか評価せず、それが後で失敗につながることが多くある。視点は多ければ多いほどいい!

5. ポートフォリオ/APIカタログの整合性の確保

あなたのプラットフォームには、APIポートフォリオ/カタログの全体的な構成に同意するプロダクトマネージャーが必要だ。カタログには様々な形があり、APIを整理することで、探しているものを正確に知らなくても必要なものを見つけやすくする。APIを機能やその他のユーザーの関心事によってグループ化して、潜在的なユーザーが利用可能なものを閲覧できるようにする。

良いカタログは、開発者が簡単に選択肢を絞り込めるように、検索やフィルタリングが可能だ。そしてカタログ内の各APIについて比較可能で理解しやすい詳細があり選択が容易になっている。

新しいAPIが提案された場合、ユースケースと基本的なネーミングを含む機能概要ができるだけ早い段階でレビューされるべきである。こうすることで、言語の整合性、再利用性、そしてより大きなプラットフォームにおける新しいAPIの全体的な "適合性 "が保証される。

あなたのイネーブルメントチームは、ポートフォリオの整合性を保つプロセスを担当するプロダクトマネージャーを持つべきであり、それぞれが管理可能な領域を担当すべきである。少なくとも、各領域のPMが定期的に調整をする場は重要だ。

これは大変なことのように思えるかもしれないが、API標準はこのようなプロセスを繰り返すことで進化するべきだと覚えておいてほしい。各APIがデザインされるにつれて、標準を改良する機会に気付くだろう。それを念頭に置いて、基本的なことが前もって課題に含まれていることを認識し、API管理者が標準の変更を提案・適用する方法を明確に理解していることが必要だ。

API設計レビューの実施

上記の前提条件をクリアしていれば、API設計レビューでやるべきことはそれほど多くない!ある領域のSMEが関与していれば、多くの場合、設計レビューは進行中の設計作業に統合できる。プラットフォームにおける "適合性 "が早い段階で確認されれば、設計レビュアーはこのAPIが全体像に属するものであるという確信を持てるはずだ。加えて、API設計者が作業を繰り返している間に構文エラーを発見した場合、様々な構文ルールの関連性について開発者を教育したり、単に構文エラーを解決する方法について説明したりする以上の、基本的な規約についての議論は必要ない。

すべてを自動化できるわけではないし、製品とアーキテクチャのニーズが衝突することもある。API設計レビューは、手作業で強制される規約をチェックし、顧客の言語を検証し(これは自動化が難しいので)、最終的な整合性を固める時間にしよう。そのような範囲を念頭に置けば、ミーティングはしばしば省略でき、非同期のディスカッションで十分なことが多い。

もっとも重要なことは、APIデザインレビューのサイクルタイムを注視することだ。 より分散化されたSMEが既存の標準と新たな標準の開発方法を快適に手に入れられれば、時間の経過とともに、はっきりと低下するはずだ。

関連記事:

• 設計/アーキテクチャ
• API
• 設計
• Architecture

あなたのメールアドレスはこちら

国を選んでください。 選択してください InfoQ.com がプライバシーポリシーに従って私の個人情報を扱うことに同意します。

We protect your privacy.