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

Jul 28, 2023

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 開発を行うことで、チームは馴染みのない技術用語で顧客を混乱させることを回避できるため、内部の理解と外部の理解が同期していることを確認します。