APIデザイン - Cloud

Talend Cloud API Designerユーザーガイド

EnrichVersion
Cloud
EnrichProdName
Talend Cloud
EnrichPlatform
Talend API Designer
task
ジョブデザインと開発 > Designing APIs
エディターを使用して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の名前をクリックするとアクセスできます。