「サンプル付き」APIレスポンスでJSONデータを使用する

APIを設計するときに、そのレスポンスでは、JSONデータを使うのは一番多くなります。本文では、さまざまな基本知識を解説した上、どのようにAPIレスポンスでJSONデータを使用するのかを皆さんに紹介します。

APIレスポンスとJSONの関連は？

JSONは、APIレスポンスで一番よく使われるデータフォーマットとして、APIレスポンスに密着している概念になります。

API (Application Programming Interface) は、アプリケーション同士がデータを交換するための手段として、APIを呼び出すと、そのAPIはレスポンスを返します。そのレスポンスのデータ形式として、JSON (JavaScript Object Notation) がよく利用されます。JSONは軽量で人が読みやすいデータ形式なので、APIのレスポンスを表現するのに適しています。

つまり、APIからレスポンスが返ってきた時、その中身のデータはJSON形式で記述されていることが多いのです。

APIレスポンスのJSONのサンプル

それでは、APIのレスポンスの中で表示されているJSONデータはどのような感じですか？この部分では、APIレスポンスのJSONデータのサンプルを皆さんに紹介します。

たとえば：天気情報を提供するAPIにリクエストを送信すると、そのAPIはJSON形式で天気データを返してきます。

{
    "place": "Tokyo",
  "weather": "sunny",
  "temperature": "25°C" 
}

また、たとえ検索エンジンのAPIを利用して「東京」で検索した場合、レスポンスは以下のようなJSON形式になるでしょう。

{
  "searchInformation": {
    "totalResults": "289,000,000", 
    "searchTime": "0.35",
    "formattedSearchTime": "0.35 seconds"
  },
  "items": [
    {
      "link": "https://ja.wikipedia.org/wiki/東京",
      "title": "東京 - Wikipedia",
      "snippet": "東京(とうきょう)は、日本の首都。人口約1,397万人(2020年)。東京都の県庁所在地である。関東地方の、本州のほぼ中央に位置する。" 
    },
    { 
      "link": "https://www.city.tokyo.lg.jp/",
      "title": "東京都 | 東京都公式サイト",
      "snippet": "東京都の公式サイト。くらし・手続き、観光・文化、健康・福祉、産業・労働、防災・環境など、東京都の総合的な情報を掲載。"
    },
    ...
  ]
}

このように、JSONデータでは、いろいろんな情報を含んで、各情報のアイテムが階層的な構造をもって表現されています。

APIレスポンスで利用できるデータフォーマット

JSONを使うのはたくさんのメリットがあるので、APIレスポンスで一番よく利用されるデータフォーマットになります。以下の理由から、JSONがAPIのレスポンスとして最適だと考えられているためです。

• シンプルで読み書きが容易
• 人が読みやすいフォーマット
• マシンが解析しやすい構造
• データサイズが小さく軽量
• プログラミング言語との親和性が高い
• 標準的なライブラリが豊富

ただし、JSONは、APIレスポンスで利用できる唯一のデータフォーマットの訳でもありません。APIのレスポンスデータの形式として、JSON以外にも以下のようなデータ形式が利用されることがあります。

• XML (Extensible Markup Language)
• YAML (YAML Ain't markup language)
• CSV (Comma Separated Values)
• バイナリデータ

この中では、JSONに続き２番目でよく使われるのがXML形式です。JSONとXMLは似ていますが、XMLの方が余計なデータが多く冗長な傾向があります。

APIのレスポンスでJSONを利用する方法

それでは、APIを設計したり、開発したりする中、APIレスポンスのデータフォーマットをJSONに定義したい場合は、どうすればいいですか？次は、Apidogという強力的なAPI管理ツールを使って、このことを実現する方法を紹介します。Apidogを使って、APIエンドポイントにリクエストを即送信してJSON形式のレスポンスを取得することもできますし、自分で設計するAPIのレスポンスをJSONに定義することもできます。

ApidogでAPIのレスポンスをJSONに定義

ステップ⒈Apidogで既存のAPIを開くか、新しいAPIを新規に作成します。そして、「Response」の部分に移動して、レスポンスのデータ構造を設定できます。

ご案内：レスポンスのデータ構造を設定するときに、手動でJSONデータを書く必要がありません。ここで直感的なUIでデータ項目を追加して、その値のタイプ（StringやIntegerなど）を定義すればOKです。

ステップ⒉データ項目を設定したら、もう少し下にスクロールして、Responseの例の部分に移動して、 例を追加をクリックします。

ステップ⒊例の名称を「成功例」に設定します。ここで 自動生成をクリックして、先に設定したデータ構造に基づいてモックサーバーを利用して、Responseの例であるJSONデータが生成されます。そして、 OK をクリックしてこのResponseの例をAPIの仕様書に追加することもできます。