🚀

Web API を取得するために前提となる知識をまとめてみた

2022/06/22に公開

API

はじめに

この記事では、Web APIからデータが欲しい！ Web APIを活用したいけど、企業の公開しているドキュメントの意味が分からないと思っている人のために事前知識として必要な情報をまとめたものです。(学部生のゼミの共有資料として使用)

対象者

この記事は下記のような人を対象にしています。

公開されているWeb API からデータを取得したい人
Web APIって何それおいしいの？と思っている人
各企業が出しているAPI仕様書の意味が全く分からない人

1. Web API とは？

HTTP通信を用いてサービスのデータを外部のアプリケーションやプログラムから扱うための機能が提供されたインターフェースのこと

*ちなみにAPIは Application Programming Interfaceの略で開発者が複雑な機能を簡単に作成できるように、プログラミング言語から提供される構造で広義の意味を持ちます。

この記事では基本的にWeb APIを対象として解説をしていきます。

2. 企業が公開しているWeb API

現在では企業が公開しているWeb API が数多くあります。それぞれに公式のドキュメントが公開されており、企業が作成した仕様(インターフェース)に乗っ取ってそのサービスやデータを利用することが可能となります。

下記は公開しているAPI仕様書の例です。

楽天トラベルAPI

https://webservice.rakuten.co.jp/documentation/simple-hotel-search

Instagram Graph API

https://developers.facebook.com/docs/instagram-api

OpenWeatherMap API

https://openweathermap.org/

e-Stat API

https://www.e-stat.go.jp/api/

3. Web API の仕組み

WebAPIは私たちが普段行うWebブラウジングと同じような仕組みを利用します。下記で実際のやりとりの図解をみてみましょう。

私たちが普段行うWebブラウジングとWebAPIの違いは下記のようになります。

Webブラウジング

Webサーバーにリクエスト(このURLにアクセスしたい)を送る。
レスポンスとしてHTML/CSSのようなテキストデータ、画像や動画をレスポンスが返ってくる。

Web API

作成したプログラム(PythonやJavascript)を使って各企業のデータに対して検索結果のリクエストを行う。
リクエストが成功すると、レスポンスで各企業に沿ったデータが返ってくる。

ここからはWeb API 内でのHTTPリクエスト、HTTPレスポンスについて詳しくみていきましょう！

4. HTTPリクエスト

Web API を取得するために企業のWebサーバーにどのようなデータや機能を利用したいかをリクエストするもの
リクエストメッセージは大きく3種類に分けられます。
1. HTTPリクエスト行
2. HTTPヘッダ(POSTメソッドで使用)
3. HTTPボディ(POSTメソッドで使用)

ここでは企業ごとにAPI仕様書が異なっていますがリクエストをする上で共通している情報が以下になります。

事前に確認する必要があるもの
- API エンドポイント (サービスを接続するためのURL )
- API キー(接続に必要なパスワード)
Webサービスにリクエストする情報(APIの仕様書で確認)
- メソッド(GET/POST)
- クエリパラメータ
- ヘッダ(POSTで使用)
- ボディ(POSTで使用)

参考 https://qiita.com/Saku731/items/6ae290f72e98723f165d

これからそれぞれの情報について具体的に確認していきましょう!

4 .1 事前に確認すべきもの

ここではWeb APIを取得する前に確認・用意する必要があるAPIエンドポイントとAPIキーについて説明します。

APIエンドポイント

エンドポイントとは接続先のこと
APIに接続(アクセス)するために与えられた固有の一意なURIを指す。

APIキー

各種データをAPI経由で取得するために必要な暗号鍵
企業のAPIを利用する場合には必要な場合が多い

4.2 HTTPリクエストをする情報(API 仕様書を参考にするもの)

ここではAPI仕様書の中で理解しておくべき用語について解説します。

HTTPメソッド

クライアントがサーバーに対してリクエストを投げるときに「サーバーにしてほしい操作」のこと
主要なメソッドは下記の4つがある。
- GET：データを取得する
- POST：データを新規作成する
- PUT：データを更新する
- DELETE：データを削除する
APIを取得する上では基本的にGETかPOSTを利用している。

クエリパラメータ

Webサーバーに伝えるためにURLに付け加える情報
基本構造は **?パラメータ(変数)名=パラメータ(変数)
複数指定では&でつなぐ
Web API の取得時にはクエリパラメータをJSON形式で設定してリクエストを送ることが多い

例 ZOZOメンズカテゴリー検索(Tシャツカットソー)のURLを確認してみましょう。

https://zozo.jp/category/tops/tshirt-cutsew/

ZOZOメンズカテゴリー検索(Tシャツカットソー)に対して、色をグレー(p_cocid=12)、サイズMのキーワード検索を行うと下記のようになります。

クエリパラメータ?p_cocid=12&size=3を追加したことによってメンズ・グレー系・サイズMを指定した検索結果が表示されていることがわかります。

https://zozo.jp/men-category/tops/tshirt-cutsew/?p_cocid=12&size=3

*これらの情報以外にもPOSTメソッドでの通信時には

ヘッダ(フィールド名: 内容で構成されたもの)
ボディ(パラメータの記述)

を行います。

5. HTTPレスポンス

HTTPレスポンスの意味はクライアントから送信されたデータをサーバが処理をしてクライアントに返信する応答のことです。

具体的なレスポンスメッセージは大きく3種類に分けられます。
1. ステータスライン
2. HTTPレスポンスヘッダ
3. HTTPレスポンスボディ(JSON)

実際にWeb APIの取得時に確認するのはレスポンスボディですが、それぞれのメッセージについて具体的に確認をしてみましょう！

5.1 HTTP ステータスライン

• サーバからのレスポンスの意味を表す3桁の数字コードのこと
• 特定のHTTPリクエストが正常に完了したかを示す

参考　https://qiita.com/unsoluble_sugar/items/b080a16701946fcfce70

具体的な結果は以下の通り

ステータスコード	内容
100番台	処理中
200番台	成功
300番台	リダイレクト
400番台	クライアントエラー
500番台	サーバーエラー

5.2 HTTPレスポンスヘッダ

フィールド名 : 内容で構成されたもの
ステータスラインの書ききれないレスポンスの情報が書かれている

詳細については下記参照

https://triple-underscore.github.io/RFC7231-ja.html#section-7

ヘッダの例

Date: Tue, 21 Jun 2022 15:52:18 GMT
Content-Type: text/html
Content-Length: 538
Connection: keep-alive
Last-Modified: Thu, 27 Feb 2020 07:10:16 GMT
ETag: "21a-59f8969af8600"
Accept-Ranges: bytes
Server: Apache

5.3 レスポンスボディ

リクエストした結果のメイン部分
Web APIでは、HTMLの代わりにプログラムで処理をしやすいデータ形式
現状データ形式としてはJSONを使うことがほとんど

JSONとは？

データ形式の一種
keyとvalueがセットになっている {key : value}
valueの種類には文字列、数値、配列、連想配列(オブジェクト)がある

JSONの例

data = {
  "args": {},  
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.79.1", 
    "X-Amzn-Trace-Id": "Root=1-62b1ed46-0b8f009a3162dc36714ec087"
  }, 
  "origin": "138.64.82.233",  
  "url": "http://httpbin.org/get" #keyが"url" valueが"http://httpbin.org/get"
}