APIデザイン

要件に基づくAPIの作成

ほとんどのテクノロジーと同様、APIも問題に対するソリューションとなります。適切なAPIをデザインするためには、以下の質問に答えて、対処している問題が明確に定義されていることを確認する必要があります:

• このAPIのターゲットとなるユーザーは誰ですか?
• コンシューマーはAPIでどのような情報を操作しますか?
• コンシューマーはAPIでどのようなアクションを実行しますか?

たとえば、食品配送会社の場合、配送サービスを提供するレストランのデータベースを参照して検索できるようにするために、パートナーネットワーク向けのAPIを構築します。

この例では、APIのターゲットは会社のパートナーになります。特定のフィルタリングやソート機能を使って、レストランに関するデータを操作し、データに対する検索クエリーを実行する必要があります。

別のサンプル: カレンダーSaaS会社の場合、世界中の他のフロントエンド開発者が新しいモバイルおよびWebアプリケーションを作成するベースとなるようなカレンダーシステムのAPIを構築します。

APIのコンシューマーについて考えることは、優れた開発者エクスペリエンスを提供するための第一歩となります。これによりAPIを目立たせることができ、エンゲージメントレベルが向上します。

APIを構成するエレメント

APIをデザインする際のキーコンセプトには、以下の4つがあります:

• [Resource] (リソース)とは、APIを通じてコンシューマーがやり取りするエレメントです。リソースはパスによって一意に識別され、APIのエンドポイントと組み合わせて、Web上のリソースの一意のアドレスが提供されます。たとえば、カレンダーはカレンダーのリストに対応するリソース名で、パスは/calendarsとなります。
• [Operation] (オペレーション)とは、リソースに対して実行できるアクションのことです。最も一般的なオペレーションは、GET、POST、PUT、DELETEです。たとえば、すべてのカレンダーをリスト表示は、カレンダーリソースのGETメソッドを使用するオペレーションの名前です。
• [Data type] (データ型)とは、ネットワーク上で交換される実際のデータを記述したものです。たとえば、Calendarは名前、所有者、およびそれに属するイベントへの参照など、カレンダーのすべてのプロパティを記述するデータ型の名前となります。すべてのCalendarオペレーションのリストでは、Calendarデータ型のリストが返されます。
• コンポーネントとは、API定義全体で再利用できるエレメントのことです。たとえば複数のオペレーションで同じクエリーパラメーターを使用する必要がある場合は、コンポーネントとして作成し、必要に応じてオペレーションで参照できます。

APIを構成するその他の便利なエレメントは以下のとおりです:

• [Endpoint] (エンドポイント)とは、Web上のAPIのメインエントリーポイントのことです。エンドポイントは、HTTPSなどのスキームと、www.calendar-api.comなどのホストで構成されます。
• [Text] (テキスト)ブロックは、APIデザインのどこにでも配置できるテキスト(マークダウンを含む)を自由に入力するために使用できます。テキストブロックを使用して、認証やエラー処理などの横断的なトピックを説明します。
• [Section] (セクション)は、リソースとデータ型を効果的にグルーピングするために使用されます。これらを使用して、APIデザインをより明確にし、開発者にとって分かりやすいものにします。左パネルのセクションにエレメントをドラッグ＆ドロップして、セクションを並べ替えることもできます。

Talend Cloud API Designerでは、左パネルの+メニューからこれらのエレメントを作成できます。

エンドポイントは一般情報画面に作成され、左パネルの上部のAPIの名前をクリックするとアクセスできます。エンドポイントは[Published] (公開済み)か[Not published] (未公開)のいずれかとなります。公開されると、ライブドキュメンテーションやAPI Portalに表示されます。