APIのドキュメンテーション

Rakuten RapidAPIで自社のAPIを公開するにあたり、開発者がAPIをブラウザ上で快適に試せるようにすることは非常に重要です。そうすることで、開発者はどのエンドポイントにクエリを行うかをスピーディーに選び、たった数回のクリックで結果のクエリを確認することができます。適切に整備された分かりやすいAPIドキュメントを作成しておくことは必須になります。


APIの認証

Rakuten RapidAPIには、APIの認証やユーザー管理の機能が備わっています。また、Rakuten RapidAPIは、それぞれのアプリに専用のRakuten RapidAPIキーを使用して、開発者が行うAPIへのリクエストの認証をすべて行い、開発者にシームレスな体験を提供しています。これにより開発者はブラウザ上でAPIをテストして、ワンクリックで登録ができます。また、別のアカウントへの登録、API資格情報の取得、資格情報を用いたAPIコールのセットアップといった手間なく、APIを使用することができるのです。

alt text

APIプロバイダは、「MashapeAPIプロキシによって送られるヘッダー」のセクションで説明する「X-RapidAPI-Proxy-Secret」ヘッダーを利用するとともに、Mashape IPをホワイトリスト化して、Rakuten RapidAPIからのリクエストを認証する必要があります。

認証が必要なAPIの場合、ひとつのアカウントでRakuten RapidAPIのユーザー全員に対応することができます。APIの「Analytics & Settings(分析情報と設定)」の「Transformations(トランスフォーム)」ページで、認証ヘッダーまたはパラメータを指定するだけで完了です。この秘密のリクエストヘッダーまたはパラメータは、あなたのプランに登録したユーザーが行うすべてのリクエストに透過的に追加されます。

alt text

エンドポイントの定義

エンドポイントがなければAPIは機能しません。ここでは、エンドポイントの定義についてご案内します。いよいよここからが本番です。

alt text

以下のモーダルウィンドウが表示されます。

alt text

  • Method(メソッド) - エンドポイントに到達する方法を定義します。作成、読み込み、更新、削除のいずれか利用可能な方法を選ぶことができます。MashapeはGET、POST、PUT、PATCH、DELETEメソッドをサポートしています。
  • Route(ルート) - エンドポイントへのルートです (なお、ベースURLは https://api.domain.com/v3 のように表示されます)。ルートはベースURLから構築されるため、最初に「/」を追加することを忘れないでください (例:「/status」)。また、ユーザーにルート内でパラメータを指定させる場合に備え、ユーザー定義パラメータを波括弧で囲むことができます。例えば「/status/{appid}」をルートとして入力した場合、追加パラメータ入力ボックスが作成され、エンドポイントを保存した際にユーザーにコンソール内のパラメータの値を指定してもらうことができます (最終結果の画像をご確認ください)。
  • Name(名称) - エンドポイントの内容を説明するための名称、または単にルートに合致する名称を設定することができます。これはドキュメンテーションエクスプローラーの右側にあるクイックメニューで表示される名称となります。
  • Description(説明文) - その名の通りエンドポイントの内容を説明するためのものであり、重要な項目です。このエンドポイントの機能をユーザーが理解するのに役立ちます。分かりやすい記述を心がけてください。

クエリ文字列パラメータの定義

クエリ文字列パラメータの追加は、特定のリクエストに追加パラメータを追加するのに用いられます。例えば、フィルター (「?limit」や「?offset」など) はリクエストによって渡される追加のクエリ文字列パラメータになり得ます。追加するには以下の画像で示されている青いボタンをクリックしてください。

alt text

  • Condition(条件) - クエリ文字列パラメータは任意、定数、または必須のいずれかで、ユーザーに変数を指定させるかどうかを決めることができます。
  • Name (名称) - パラメータに付けられる名称です。「param=text」ではこの値の設定は「param」となります。
  • Type(種別) - パラメータ、番号、文字列、ブーリアン (true/false)、またはバイナリの値の種別を設定します。特殊文字を指定した場合、URL符号化形式に変換されます。例えば、「ü」は「%C3%BC」になります。
  • Value(値) - 条件を「定数」に設定した場合、ここでクエリパラメータの値を実行することができます。そうしなかった場合、これはデフォルトの値を入力する場所となります。
  • Description(説明文) - クエリパラメータの内容を短い言葉で説明しましょう。

alt text

リクエストヘッダー

クエリ文字列パラメータと同様に、APIエンドポイントに渡すためのカスタムヘッダーを指定することができます。「Add header(ヘッダーを追加)」ボタンを押すだけでオプション付きのダイアログがポップアップします。

alt text

以下のモーダルウィンドウが表示され、クエリパラメータダイアログと同様にヘッダーの条件、名称、種別、値、説明文の値を設定することができます。

alt text

  • Condition(条件)- クエリ文字列パラメータは任意、定数、または必須のいずれかで、ユーザーに変数を指定させるかどうかを決めることができます。
  • Name(名称)- パラメータに付けられる名称です。「param=text」ではこの値の設定は「param」となります。
  • Type(種別)- パラメータ、番号、文字列、ブーリアン (true/false)、またはバイナリの値の種別を設定します。特殊文字を指定した場合、URL符号化形式に変換されます。例えば、「ü」は「%C3%BC」になります。
  • Value(値)- 条件を「定数」に設定した場合、ここでクエリパラメータの値を実行することができます。そうしなかった場合、これはデフォルトの値を入力する場所となります。
  • Description(説明文)- クエリパラメータの内容を短い言葉で説明しましょう。

ペイロードの定義 (POST、PUT、PATCHのみ)

エンドポイントに対してクエリを行うメソッドにPOST、PUT、またはPATCHメソッドを指定する場合、ペイロードも定義する必要があります。ペイロードは単一形式の値またはモデルとして追加することができます。値は自分が必要とする数だけ追加することができます。

ダイアログから2つのオプションが利用可能になっています。

alt text

ペイロードを形式符号化パラメータとして定義する

形式符号化パラメータとして定義されたペイロードは、引数をペイロードに渡すにあたって最もシンプルな方法となります。

alt text

  • Condition(条件)- 任意、定数、または必須のいずれかから選んでください。
  • Name(名称) - パラメータに付けられる名称で、値の前に指定されます。「color = red」を渡す場合、これは色を参照します。
  • Type(種別)- パラメータの値の種別を設定します。
  • Value(値) - 条件を「定数」に設定した場合、パラメータの値を実行することができます。そうしなかった場合、これはデフォルトの値 (ユーザーが変更することができます) を入力する場所となります。
  • Description(説明文) - パラメータの内容を短い言葉で説明しましょう。

ペイロードをモデルとして定義する

alt text

この方法でエンドポイントに投稿するペイロードを定義することで、数多くのパラメータを指定することができるためかなりの柔軟性が得られます。

  • Model Name(モデル名)- 他のモデルと識別するためにこのモデルに割当てる名称です。
  • Format(形式) - JSON、バイナリ、またはプレーンテキストのいずれかでペイロードをエンドポイントに渡すことを選ぶことができます。
  • Description(説明文) - モデルの説明文を入力することで、何を渡すことを求められているかをユーザーに伝えます。
  • Sample Body(サンプル本文) - 形式によって変わります。JSONの例: { “sample”:“never fails” }