【クイックスタート：パート1】API Designerで最初のAPIを設計する方法

※この記事は、下記MuleSoftの記事を、許可を得て翻訳したものです。
https://developer.mulesoft.com/guides/quick-start/designing-your-first-api

多くの開発者は日々の開発でAPIを使用する経験はありますが、REST APIをゼロから設計することは少ないかもしれません。このチュートリアルでは、MuleSoftのAnypoint Platformを使用してAPIを簡単に作成する方法を説明します。 APIの設計経験がない開発者でもAPI仕様を約5分で公開する方法ことができます。
このチュートリアルは本番環境に対応したスケーラブルなAPIとシステム連携を構築するためのベストプラクティスについて説明する4部構成のクイックスタートチュートリアルシリーズの一部です。

API開発の最初のステップは、APIの動作をブレインストーミングすることです。APIがPOSTリクエストで200の有効な応答を返し、GETリクエストで許可されていない405メソッドを返すようにしますか？RESTful APIまたはSOAP APIを設計しますか？ APIをHTTP、HTTPS、またはその両方にしたいですか？APIリクエストでどのデータ型を受け入れたいですか？これらの質問はすべて、MuleSoftのAPI DesignerでAPIを構築するときに設定できるパラメーターとなります。

API仕様はAPIの動作とAPIが外部システムまたは外部APIと統合する方法を開発者に伝えるために使用されます。API仕様の言語はRAMLもしくはOpenAPI（以前のSwagger）が一般的です。これらの言語はAPIとのインターフェース方法のルールを記述および視覚化するために使用されます。このチュートリアルでは、API Designer上でRAMLによってAPI仕様を生成しExchangeに公開する手順を説明します。

最初のAPIでは内部データベースから連絡先のリストを取得し、Salesforceにリードとしてアップロードする連携を作成しましょう。簡単にできそうですね。最初に下記にリンクからAnypoint Platformのトライアル版にアカウントを作成してください。

サインアップ

Anypoint PlatformにログインしたらDesign Centerに移動します。Design Centerに移動したら、「+ Create New」ボタンをクリックし、以下に示すように「Create API specification」を選択します。

「Create API specification」ボタンをクリックした後、新しいAPI仕様の名前を入力します。このチュートリアルでは「Contact API」とします。エディタは「Visual editor」を選択します。 Visual EditorはコーディングなしでAPI仕様の枠組みを作成できる直感的なビジュアルインターフェイスです。

「Create Specification」ボタンをクリックすると、Design Centerに移動し、「API Summary」ページが表示されます。RAMLと呼ばれる言語で生成されるAPI仕様は画面の右側に表示されています。

最初のAPIでは「Title」、「Version」、「Protocols」、および「Description」を下記のように設定します。 Protocolsは「HTTP」と「HTTPS」の両方を受け入れるようにし、APIをバージョンは「1」に設定してください。

次に、画面の左側の「Data Types」の横にある「+」> 「Add data type」をクリックします。 Nameに「Contacts」と入力しData Typeを作成します。Data Typeを指定すると情報が追加されAPIのRAMLファイルで参照されます。フローの各カードは入力と出力にあるデータのフォーマットと構造を自動的に検出するため、Data Typeを作成するとフローを作成するときに役立ちます。

Data Typeを作成したら、以下のスクリーンショットに従ってData Typeに「FirstName」、「LastName」、「Email」、および「Company」の4つのプロパティを追加します。 各属性が文字列として定義されていることを確認してから「Example」ウィンドウに移動し、「Edit」タブを押下して以下に示すようにいくつかのサンプルデータでJSONを定義します。

Data Typeを作成したので、次にAPIへのHTTPリクエストを受け入れるための新しいリソース（APIエンドポイントとも呼ばれる）を作成する必要があります。API Summaryページの左側にある「Resource」タブをクリックし、「+」ボタンをクリックして新しいリソースを作成します。アプリケーションにHTTPリクエストを送信するためのエンドポイントURLを定義する新しいResourceに「/contacts」と名前を付けます。

このAPIではHTTP GETリクエストのみエンドポイントに受け入れられることを許可します。指定したエンドポイント名の下にあるGETボタンをクリックして、APIが従う仕様（ルールと考えることができます）を追加します。

「Summary」タブで「Name」に「Get all contacts」と指定します。

「Responses」タブで、「Add New Response」ボタンをクリックして、HTTPステータスコード200-OKを追加します。 「Add Body」ボタンをクリックし、「Media Type」が「application/json」、「Type」に「Array」を指定します。 次に、「∨」アイコンをクリックし、Typeに上記で作成したData Typeの「Contacts」を指定します。

API仕様が正常に作成されたのでAPIをテストして期待どおりに機能していることを確認します。画面右上に「Mocking Service」スライダーがあり、Mocking ServiceのURLを生成するにはスライダーを有効にする必要があります。Anypoint Platformには、Mocking Serviceウィンドウ（画面右下の「Try it」タブをクリック）でさまざまな入力パラメーター、ヘッダー、本文メッセージをテストするオプションがあります。この機能を使用すると、デプロイする前に、APIがさまざまなタイプのリクエストをどのように処理するかをテストできます。

APIをテストするにはMocking Serviceを有効にして「Send」ボタンをクリックします。応答フィールドでは、1つのエントリが応答で返されていることがわかります。 Postmanというアプリケーションをダウンロードして使用しMocking ServiceのURLにGETリクエストを送信して同じ応答を確認することもできます。

これで「Contact」APIをExchangeに公開する準備ができました。Exchangeは組織全体で再利用および共有できるコネクタ、API、およびテンプレートのMarketPlaceです。APIをExchangeに公開するときにAPIをプライベートにするか、ビジネス組織内の誰にでも公開するか、パブリックにするかを定義できます。さらにAPIをダウンロードして、将来の統合やプロジェクトで再利用できます。APIを公開するにはDesign Centerの画面右上にある「Publish」をクリックし「Publish to Exchenge」を選択します。公開後にAPIがExchangeにリストされます。つまり、APIをAnypoint Studioプロジェクトにインポートして、最初の統合を構築できるようになります。

Exchangeでは写真を追加したり、タイトル、説明を編集したり、公開したAPIについて評価やコメントを追加したりできます。次のチュートリアルに進む前に、自分で公開したAPIを自由にカスタマイズしてください。

MuleSoftのAnypoint Platformを使用して最初のAPIを構築および公開することが出来ました。次のチュートリアルでは、APIをAnypoint StudioにインポートしデータベースからJSON形式でデータを返す簡単な統合を構築する手順を説明します。ほんの数分で最初のmuleアプリケーションを開発する方法を学ぶことができます。