ニュース

Jul 04, 2023

API 設計レビューは廃止されました。 API 設計レビュー万歳!

Articoli sulla home page di InfoQ Progettazione API

InfoQ ホームページ アーティクル API 設計レビューは終わった。 API 設計レビュー万歳!

2023 年 5 月 22 日 8 分で読む

による

ジェイソン・ハーモン

によってレビュー

トーマス・ベッツ

API を大規模に設計する過程では、一貫性を保つために意図的な努力が必要です。 多数の API と真のプラットフォームのように見えるものの主な違いは、一貫性です。 この場合の一貫性とは、複数の API を使用する場合、命名規則、ページングなどの対話パターン、認証メカニズムなどの要素が全体的に標準であることを意味します。

従来、審査委員会は、開発が完了したと思われるときに遅延を引き起こす発見を行い、API 開発者にトラウマを与えてきました。 さらに悪いことに、委員会による設計が優先され、進捗が滞ったり、開発者が苦痛を完全に回避するためにプロセスを回避する方法を見つけたりする可能性があります。

最新のプラットフォームを真に解放するには、分散型ガバナンスによる有効化が、よりスケーラブルで魅力的なアプローチとなります。 これは単に、各ドメインまたは機能領域に、API 開発者にとって適切なガイドとなる標準およびアーキテクチャ全体について教育を受けた主題専門家がいることを意味します。

アイデンティティを保護します。 安全なデジタル サービス。 Web およびモバイル アプリケーションへのスケーラブルかつ安全なユーザー アクセスを可能にします。 無料トライアルを開始。

さらに重要なのは、開発の大部分が完了する前に API 設計に同意することで、配信期間を危険にさらす土壇場での発見を大幅に回避できることです (設計優先のアプローチと呼ばれることがよくあります)。 OpenAPI (HTTP/「REST」API の事実上の標準) のような仕様フォーマットを使用すると、開発前に API を定義できるため、より早い段階での調整と問題の特定が可能になります。

この文脈を念頭に置いて、API 設計レビューを実施する方法と、プロセスを開発して、タイムラインの長期化と開発者の関与の欠如を回避するために組織を準備する方法を詳しく見てみましょう。

スムーズなプロセスを確保するための重要な前提条件をいくつか示します。

API の使用は非常に洗練されたエクスペリエンスであるため、言語の影響は他のほとんどの設計領域よりも不釣り合いに高くなります。 チーム メンバーごとに、さまざまな用語の定義や説明の方法が若干異なる場合があり、これが API チームの混乱と生産性の低下に現れます。

API ポータル/ドキュメントは優れた開発者エクスペリエンスに不可欠ですが、適切に設計された API は、あまり考えなくてもストーリーのほとんどを伝えることができます。 用語が消費者にとって馴染みがあり、対話パターンが明白であれば、エクスペリエンスは迅速かつ苦痛なく行えます。 一貫性は、多数の API と 1 つのプラットフォームのように感じられるものとの間のエクスペリエンスの主な違いです。

API プログラムとガバナンス プロセスを確立するときは、共有言語から始めます。 最初は不可能に思えるかもしれませんが、プラットフォーム向けに顧客中心の共有語彙/文法を定義することは不可欠であり、組織全体のアクセラレータとなります。 企業内では多くの用語がさまざまな意味を持っている可能性があり、さらに悪いことに、これらの用語は最終消費者が認識すらしない用語であることがよくあります。

この下調べを事前に行うことで、API の設計中に名前付けをめぐる競合が回避されます。 関連する関係者と各ドメインを検討して共通の用語を定義し、API 設計者に対する広範な可用性と認識を確保します。 そして、用語の内部標準化を決めたら、それが外部のニーズにも適合するかどうかを確認することを忘れないでください。 顧客言語を使用し、顧客中心の視点で API 開発を行うことで、チームは馴染みのない技術用語で顧客を混乱させることを回避できるため、内部の理解と外部の理解が同期していることを確認します。

API コンシューマーが API 間で異なるモデルやパラメーターに遭遇すると、混乱し、イライラし、時間のかかるプロセスになる可能性があります。 たとえば、連絡先情報を参照する 1 つの API を使用し、同じプラットフォーム内の次の API がまったく異なるモデルを使用する場合、多くの場合、消費者はこれらの違いを解決する必要があります。 さらに悪いことに、このデータの処理におけるシステム上の違いが明らかになり、機能的な違いが生じる可能性があります。

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

共通のコンポーネントが増えるほど、一貫性、再利用性が向上し、さらなるコラボレーションの機会が得られ、効率が向上します。 開発者の世界では、私たち全員が「DRY メソッド」 (Don'trepeat Yourself) が大好きで、共有コンポーネントが多ければ多いほど、同じものを何度も最初から作成する必要がなく、イノベーションが容易になります。 共有コンポーネントを使用すると、チームを迅速に拡張できるため、API チーム以外の新しい開発者や関係者を簡単にトレーニングできます。

単純な命名規則、対話パターン、および認証メカニズムの大部分については、スタイル ガイドを使用した自動化を提供して、できるだけ早く不一致にフラグを立てることができます。

最初のスタイル ガイドは 2013 年から 2015 年にかけて開発され、API 開発チームのルック アンド フィール (別名 DX) に対する期待を設定しました。 設計の一貫性の必要性は API プラットフォーム開発の当初から明らかであり、Paypal (実際に私も当時このチームの一員でした!) と Heroku による初期の取り組みにより、成功したプログラムからの最初のスタイル ガイドのいくつかが生まれました。公開で共有されます。

スタイル ガイドを支援するために利用できる自動化ツールはさまざまありますが、オープンソース ツール Spectral は、API リンティング ルールセットを定義するための標準として登場しました。 パスやパラメータなどの規則を事前に調整し、自動リンティング ルールを定義すると、どの規則が「正しい」かという競合による遅延を回避できます。 一度話し合い、ルールを決めてください...それについては二度と話さないようにしてください。 lint エラーをなくすだけです。

自動化できない設計標準については、文書化して API 設計者が簡単に利用できるようにする必要があります。 自動化されたルールと手動で検証されたルールの重要性を説明するトレーニングは、開発者がその取り組みを完全にサポートする動機を築き、予期せぬ事態や摩擦を避けることができます。

API 有効化チームは、これらの設計標準を管理し、コミュニティを育成するために存在する必要がありますが、各機能領域またはドメインで権限を有効にする必要があります。

API 標準は重要ですが、システム上の制約、特定の顧客ニーズ、組織の長所と短所に関する専門分野の知識は、その世界の一部である専門家が最も適切に扱うことができます。 集中管理された API イネーブルメント チームのメンバーが社内のすべてのことを知っていることが期待される場合、配信の遅延や開発者の関与の低下につながるボトルネックがほぼ確実に発生します。

トレーニング ワークショップは、API 標準の重要性の認識を広めるための強力な手法となり得ます。 さらに、ガバナンス権限を提供する適切な中小企業も見つかることがよくあります。 API に対する情熱を表明し (私は API のことを「反逆者の集団」とよく呼びます)、一貫性と標準の関連性についての認識を示し、同僚やレポートから技術的な敬意を払っている個人を探してください。

API の開発を成功させるには、組織内の多くの人々が関与することになります。多くの場合、対照的なスキルセットを持った人々が関与し、API を構築してデプロイする人もいれば、ビジネス上の問題の戦略的側面に携わって API の価値を特定する人もいます。 設計レビューに誰を参加させるかについては、ビジネス関係者も忘れないでください。 多くの場合、技術的な側面だけを考慮すると、後で失敗する可能性があります。 視点が多ければ多いほど良いです!

プラットフォームには、API ポートフォリオ/カタログの全体的な構成に同意するプロダクト マネージャーが必要です。 カタログにはさまざまな形式があり、探しているものを正確に知らなくても必要なものを簡単に見つけられるように API が整理されています。 これにより、潜在的なユーザーは、機能またはその他のユーザーの懸念事項ごとにグループ化された利用可能な API を参照できます。

優れたカタログは検索またはフィルタリングが可能なため、開発者はオプションを簡単に絞り込むことができ、カタログ内の各 API について比較可能なわかりやすい詳細が提供され、今後の明確な道筋が示されます。

提案された新しい API については、使用例および基本的な命名を含む機能の概要をできるだけ早くレビューする必要があります。 これにより、言語の調整、再利用性、およびより大きなプラットフォームの観点に対する新しい API の全体的な「適合」が保証されます。

イネーブルメント チームには、ポートフォリオ調整プロセスを所有するプロダクト マネージャーが必要であり、各マネージャーが管理可能なドメインのコレクションを所有している必要があります。 少なくとも、ドメイン固有の PM が連携に関する議論を行う定期的な場が重要です。

それは大変なことのように思えるかもしれませんが、API 標準は反復を通じて進化する必要があることを忘れないでください。 各 API が設計されるにつれて、標準を改良する機会があることがわかります。 これを念頭に置いて、事前の宿題で基本事項がカバーされていることを確認し、API ガバナーが標準への変更を提案および採用する方法を明確に理解していることを確認してください。

上記の前提条件を満たしていれば、API 設計のレビューで行うことはあまりありません。 ドメイン中心の SME が関与している場合は、多くの場合、設計レビューを進行中の設計作業に大幅に組み込むことができます。 プラットフォームへの「適合性」が早い段階で調整されていれば、設計レビュー担当者は、この API が全体像に属していると確信できるはずです。 さらに、API 設計者が反復処理中に lint エラーを発見した場合、さまざまな lint ルールの関連性について開発者を教育すること、または単に lint エラーを解決する方法について開発者を教育すること以外に、基本的な規則について議論すべきではありません。

すべてを自動化できるわけではなく、製品とアーキテクチャのニーズが矛盾する場合もあります。 API 設計のレビューでは、手動で適用された規則をチェックし、顧客の言語を検証し (これは自動化が難しいため)、最終的な調整を強化します。 その範囲を念頭に置くと、多くの場合、会議を省略でき、非同期のディスカッションで十分な場合が多くなります。

最も重要なことは、API 設計レビューのサイクル タイムに注意を払うことです。分散化が進む中小企業が既存の標準や新しい標準の採用方法に慣れてくると、時間の経過とともに明らかに減少するはずです。

InfoQ で執筆することで多くの扉が開かれ、キャリアの機会が増加しました私にとって。 専門家や思想的リーダーと深く関わり、自分が扱ったトピックについてさらに学ぶことができました。 また、学んだことをより広範なテクノロジー コミュニティに広め、テクノロジーが現実世界でどのように使用されているかを理解することもできます。

私は今年初めに InfoQ のコントリビューター プログラムを発見し、それ以来楽しんでいます。 ソフトウェア開発者のグローバル コミュニティと学習を共有するためのプラットフォームを提供してくれたことに加えて、InfoQ のピアツーピア レビュー システムのおかげで私の執筆力は大幅に向上しました。 。 ソフトウェアの専門知識を共有する場所を探している場合は、InfoQ への貢献を始めてください。

私はテクノロジーを最新の状態に保つ方法として InfoQ .NET キューのニュースを書き始めましたが、それ以上に多くのことを得ることができました。 知識豊富な人々に会い、世界的な知名度を得て、ライティングスキルを向上させました。

InfoQ の編集者になったことは、私のキャリアの中で最良の決断の 1 つでした 。 それは私に挑戦をもたらし、非常に多くの点で私を成長させてくれました 。 もっと多くの人に来てもらいたいです私たちのチームに参加してください。

InfoQ はフルタイムの編集長を募集しています C4Media の国際的な、常にリモートのチームに参加します。 私たちと一緒に、現代の最も革新的なテクノロジーを取り上げ、世界で最も優秀なソフトウェア実践者と協力し、160 万を超える開発チームが新しいテクノロジーや実践を導入して、ソフトウェアとチームが提供できるものの限界を押し上げるのを支援してください。

毎週火曜日に送信される InfoQ の先週のコンテンツのまとめ。 250,000 人を超える上級開発者のコ​​ミュニティに参加してください。 例を見る

私たちはあなたのプライバシーを守ります。

コメントを投稿するには、InfoQ アカウントを登録するか、ログインする必要があります。 しかし、登録の背後にはさらに多くのことがあります。

InfoQ のエクスペリエンスを最大限に活用してください。

許可される HTML: a、b、br、blockquote、i、li、pre、u、ul、p

許可される HTML: a、b、br、blockquote、i、li、pre、u、ul、p

許可される HTML: a、b、br、blockquote、i、li、pre、u、ul、p