本投稿は、HERE Developer BlogのHERE with Postmanを日本語に抄訳し、一部内容を最新化してます。アップデートしています。
(元記事依存で内容が古い部分、リンク切れ、日本語が美しくない部分追って修正します🙏)
HERE with Postman
RESTful API（REST API）は、アプリケーションを構築するためのサービスと通信する最も簡単な方法の一つです。HEREは、フリーミアムアカウントを通じて開発者に20以上のAPIを提供しています。これらのAPIは、REST APIとして、またはJSラッパーとして利用可能です。REST APIの驚くべき点は、プラットフォーム、フレームワーク、言語に依存しないことです。ですから、様々な方法で呼び出すことができます。さらに、REST APIのレスポンスをテストするためのツールがいくつかあります。その一つがPostmanです。
Postmanは、REST APIをテストする方法にとどまらず、多くのことができます。自分自身のAPIを構築し、それに関するドキュメントを書くことも可能です。今日は、Postmanを使用してHERE REST APIを効率的に呼び出すためのヒントとコツについてお話しします。まず、私のお気に入りの ジオコーディングと検索API を使って、シンプルなリクエストを作成してみましょう。
リクエストの作成
Postmanウィンドウの構造を見ると、REST呼び出しを行うためのいくつかのコンポーネントがあります。シンプルな呼び出しを行うために、私たちは主に3つに注目します：リクエストタイプ、リクエストURL、そしてレスポンスです。ジオコーディングと検索APIの「リクエストの構築」セクションに行くと、API呼び出しの構造が同じであることがわかります。ドキュメントに従って、私たちはリクエストタイプとしてGETを選択します。次に重要なのはリクエストURLです。この場合、単純なジオコーディングリクエストを行いたいので、URLは https://geocode.search.hereapi.com/v1/geocode となります。これに続いて、この呼び出しを行うためのパラメータがあります。ジオコーディングリクエストを行うために最低限必要なパラメータは、ロケーションを取得したいフリーフォームテキストクエリ q です。それでは、URLにこれを追加しましょう。
URLは https://geocode.search.hereapi.com/v1/geocode?q=Brandenburg+gate%2C+Berlin のようになります。HERE API呼び出しにおいて最も重要なパラメータは認証です。このリクエストのために、私はHEREのフリーミアムデベロッパーアカウントのプロジェクトページからREST APIキーを使用します。APIキーを追加すると、私のURLは https://geocode.search.hereapi.com/v1/geocode?q=Brandenburg+gate%2C+Berlin&apiKey={MY_REST_API_KEY} のようになります。これをPostmanウィンドウのリクエストURLバーにコピーし、「送信」をクリックします。レスポンスセクションでこのAPIのレスポンスが表示されます。
パラメータ
前のステップで、主なAPIリソースの後にURLに追加したパラメータは、Postmanウィンドウのparamsセクションに反映されます。したがって、すべてのパラメータを含むリクエストURLを作成してからそれを入力する代わりに、APIの基本URLを追加し、paramsセクションにそれぞれの値とともにパラメータを追加し続けることができます。また、隣にあるチェックボックスをトグルすることで、パラメータを無効にしたり有効にしたりすることもできます。上記のジオコーディングと検索リクエストで、私はレスポンスで1つの結果だけを得たいので、パラメータlimitを追加します。
注) 日本向け下記のドキュメントも参照ください。
https://www.here.com/docs/bundle/geocoding-and-search-api-developer-guide/page/topics/japan.html
環境
上のスクリーンショットで私のAPIキーが見えないことに気づいたかもしれません。これは、私がそれらをPostman環境に保存しているためです。Postmanの環境では、APIキーまたは他の認証キーを保存しておくことができ、リクエストを作成するたびにそれらを入力する必要がなくなります。これは、異なる企業やプラットフォームのAPIを使用している場合にも非常に便利です。それぞれのAPIプラットフォームのためにいくつかの環境を持つことができます。
コレクション
いくつかの異なるAPIエンドポイントに対して複数のリクエストを作成した後、将来それらを使用したいと思うかもしれません。今回は、fernsehturmのロケーションを検索したいと思いますが、リクエスト全体を最初から作成したくありません。Postmanでは、リクエストを保存し、コレクションとしてグループ化することができます。したがって、 ジオコーディングと検索 のすべてのエンドポイント（ジオコーディング、リバースジオコーディング、ディスカバー、オートサジェスト、ブラウズ、ルックアップ）のリクエストを「HEREジオコーディングと検索」というコレクションに保存し、いつでもエンドポイントをテストしたいときに参照できます。これらのコレクションを共有したり、他のコレクションをウィンドウにインポートしたりすることもできます。
参考情報 - ベアラートークンの作成
上記の例では、ジオコーディングと検索APIにアクセスするためにAPIキーを使用しました。HEREはOAuth 2.0トークンを使った認証も提供しています。これらのベアラートークンはPostmanで生成できます。この チュートリアル を見て、楽しくHERE APIコレクションをPostman上で作成してみてください！
関連リンク
HERE API 公式ドキュメント: https://developer.here.com/documentation/
Postman 公式ドキュメント: https://learning.postman.com/docs/