APIの仕組みが分かる・使いこなせる人材になれる記事（Pythonコード付き） #Python

株式会社デジサクがお送りするプログラミング記事、
今回はAPI(Web API)について扱っていこうと思います。

はじめに

プログラミングを勉強していて、APIってなんだ？と感じた経験はないでしょうか。

「そもそもAPIを使って何ができるの？」
「どうやって使うの？」

こういった悩みを解決するには どのAPIにも共通する仕組み を理解すると良いです。
具体的なPythonのコードまで紹介するので、読み終わる頃にはAPIの使い方が身に付いているはずです。
※本記事では「WebAPI」のみ扱います。※API・WebAPIの違いを知りたい方はこちら

章構成は以下の通りです。

APIとは（APIを使うメリット）
APIを理解する
APIサービスの例
Pythonコードサンプル

SNS でも色々な情報を発信しているので、記事を読んで良いなと感じて頂けたら
Twitterアカウント「Saku731」もフォロー頂けると嬉しいです

APIとは（APIを使うメリット）

APIは「Application Programming Interface」の略です。
直訳すると以下の様になります。

アプリケーション（Application）を
プログラミング（Programming）を使って
繋ぐ（Interface）

※Applicationは「Webサービス」「システム」といった意味です。

もう少し深ぼりすると、APIが必要とされる最大の利点は
『自分が作ったWebサービスに、他の人が作った便利な機能を借りてくる』
これに尽きると考えています。

つまり、自分で苦労してゼロから開発する必要が無くなるのです。
例えばECサイトを開発する際、皆さんはどちらを選ぶでしょうか？

自分でクレジット決済機能を作る
カード会社が提供しているクレジット決済APIを使う

このように**「自分で作らない」**という選択肢がAPIの最大メリットです。

APIを理解する

APIの利点が分かったところで、その仕組みを理解して行きましょう。
大きく分けて３つの知識が必要となります。

１）Webの仕組み
２）HTTPリクエスト
３）HTTPレスポンス

１）Webの仕組み

普段から何気なく使っているインターネットはWebのおかげで成り立っています。
Webは『インターネット上で文章や画像など、あらゆる種類のデータを送る仕組み』です。

なので、APIで他の人が作ったWebサービスを借りてくるには当然ながらWebの理解が必要です。
Webを理解するためには以下３つを押さえましょう。

HTTP（Hyper Text Transfer Protocol）
URL（正確にはURI）
ハイパーテキスト（HTMLなど）

文章で整理するとこういった具合です。

Webとは、、
『HTTPという通信の約束に従って』
『URLで指定する場所（サーバー）との間で』
『ハイパーテキスト（情報）をやり取りする』ための仕組み。

Webを詳しく理解するためには何冊も本を読まないといけないですが、
「URLで指定したサーバーと情報のやり取りを行う技術」だと理解すれば十分です。

このWeb技術を使用して自分のWebサービスと**他の人が作ったWebサービス（サーバー）**の間で簡単に情報のやり取りを実現する仕組みがAPIなのです。

そして、具体的にAPIを使いこなすには、Webが採用しているHTTP（通信上の約束事）を使用する必要があります。「相手へ情報を送信するHTTPリクエスト」と「相手から情報を受け取るHTTPレスポンス」の２種類があるので以降で理解して行きましょう。

２）HTTPリクエスト

まず自分から相手にデータを送信するHTTPリクエストです。
API経由で**他の人が作ったWebサービスに「機能を使わせて下さい」**といったリクエストを投げる処理です。

WebサービスごとにAPIの使い方が異なって見えるのですが共通する基礎があります。
どんなAPIを使うときでも共通して以下の情報を用意すれば良いです。

Webサービスに接続するための情報（サービス登録時に手に入る）
- API エンドポイント（サービスに接続するためのURL）
- API キー（接続に必要なパスワード）
Webサービスに送信する情報（APIの仕様書で確認できる）
- メソッド（主にPOSTかGET）
- クエリパラメータ（使用するAPI・サービスの種類など詳細を指定）
- ヘッダ（データの種類や、API キーなどの認証情報を入力　※POSTメソッドで指定する）
- ボディ（APIと送受信したい情報を入力。※POSTメソッドで指定する）

これらの大項目はどんなAPIでも共通なのですが、細かな内容で違いが出てきます。
各サービスが公開している「API仕様書」で必要な内容を確認しましょう。
※慣れるまではQiitaに投稿されているサービス利用手順を読むのが１番おススメです。

各地の天気を取得できるAPIを使用するとしたら、こういった具合に情報整理されます。
POST・GETどちらを使用すべきかはAPI仕様書に書いてあるので、最初は意識しなくても大丈夫です。
※違いを詳しく知りたい方は【こちら】を参照ください。

なお、POST, GET以外にもPUT, DELETEというメソッドがあり、
大まかには以下のように説明されます。

GET：データを取得する
POST：データを新規作成する
PUT：データを更新する
DELETE：データを削除する

天気予報API（POSTメソッドの場合）

Webサービスに接続するための情報
- API エンドポイント：https:/world_weather.com/api　※架空のURLです
- API キー：aaabbbccc
Webサービスに送信する情報
- メソッド：POST
- クエリパラメータ：service=Weatyer（使用するサービスを指定）
- ヘッダ：application/json（データの種類）
- ボディ：date=today, area=Tokyo（送受信したい情報を入力）

プログラムのサンプルとしては以下の様になります。
※実在しないAPIなので実行してもエラーになります。

# ライブラリのインポート
import requests

# APIに接続するための情報
API_Endpoint = https:/world_weather.com/api
API_Key = aaabbbccc

# APIに送信する情報
headers = {'Content-Type': 'application/json', 'key':API_Key}
body = {date='today', area=Tokyo}

# API接続の実行
result = requests.post(API_Endpoint, data=json.dumps(body), headers=headers)

天気予報API （GETメソッドの場合）

Webサービスに接続するための情報
- API エンドポイント：https:/world_weather.com/api　
- API キー：aaabbbccc
Webサービスに送信する情報
- メソッド：GET
- クエリパラメータ：service=Weatyer, date=today, area=Tokyo
  （GETメソッドでは全てクエリパラメータに納めます）

GETメソッドについてはサービスにもよりますが以下の様な書き方が一般的です。

①原則：エンドポイント（URL）にすべての情報を含める

# ライブラリのインポート
import requests

# APIに接続するための情報（「?」の後ろに「&」で条件を繋いでいく）
API_Endpoint = https:/world_weather.com/api?Key=aaabbbccc&date='today'&area='Tokyo'

# API接続の実行
result = requests.get(API_Endpoint)

② requests モジュールの機能：POSTみたいに情報を切り分ける

こちらの記述方法はPOSTに似ていますね。
裏側では「①原則」と同じ形でデータ送信されるので結果は同じです。

# ライブラリのインポート
import requests

# APIに接続するための情報
API_Endpoint = https:/world_weather.com/api
API_Key = aaabbbccc

# APIに送信する情報
headers = {'key':API_Key}
params = {date='today', area=Tokyo}

# API接続の実行
result = requests.get(API_Endpoint, headers=headers, params=params)

３）HTTPレスポンス

API経由でWebサービスにHTTPリクエストを送ると、HTTPレスポンスという『返事』が送られてきます。
この『返事』を自分のWebサービス上で表示させることで、自分で１から開発する手間が省けます。

例えば、、
『リクエスト：天気を教えてください。今日, 日本, 東京』

『レスポンス：晴れのち曇りです』

APIサービスの例

ここまででAPIの概要を理解したので、実際に利用できる無料のAPIサービスを使用してみましょう。

使用するAPIのサービス概要

Livedoor天気情報サービス Weather Hacks を使ってみます。
無料で日本全国142ヵ所の天気予報を「今日・明日・明後日」まで取得する事が出来ます。

API仕様書を見てみる

上記リンクをクリックしてAPI仕様書を見てみましょう。
サービスによって項目数・名称は異なりますが、おおむね確認すべき順番は以下の通りです。

API エンドポイントは？
API Keyの取得方法は？
POSTかGETか？
クエリパラメータは？
ヘッダ・ボディで送信すべき情報は？

順番に整理して行きましょう。今回は無料サービスということもあって非常にシンプルです。

API エンドポイントは？
http://weather.livedoor.com/forecast/webservice/json/v1
※エンドポイントはURL/URI といった名称で記載されていることがあります。
API Keyの取得方法は？
特に記述がないので、認証不要（API Key不要）で利用できるサービスのようです。
POSTかGETか？
このサービスではGETメソッドを使用します。今回の様に仕様書を一見してもメソッドが明記されていないケースでは以下のように判別します。
- 「エンドポイント（URL）＋クエリパラメータ」の形で使用する記述がある場合：GETの場合が多い
- それ以外：POSTの場合が多い
クエリパラメータは？
天気予報を取得したい地域（ city ）を指定すれば良いようです。
サンプルで書いてある「久留米：400040」を使用してみましょう。
ヘッダ・ボディで送信すべき情報は？
GETメソッドを使用するのでヘッダ・ボディは用意する必要ありません。

Pythonコードサンプル

リクエストに必要な情報が分かったのでPythonでAPIにリクエストを投げてみましょう。

APIリクエストの送信

コードをコピペしてそのまま実行して頂ければ大丈夫です。

# APIリクエストに必要なライブラリ
import requests
# URL＋クエリパラメータ
url = 'http://weather.livedoor.com/forecast/webservice/json/v1?city=400040'
# APIリクエストを送信
tenki_data = requests.get(url).json()

戻ってきた結果を print() で表示するととても判読が難しい表示になります。
このままでは使用できないのでJSONデータの使用方法を理解する必要があります。

print(tenki_data)

APIレスポンスのJSONデータ確認

APIから戻ってきたデータは JSON形式 であることが多いです。詳細な説明は割愛しますが、コードの requests.get(url).json() に含まれる .json() の部分でJSON形式から辞書型に変換した上で使用する事が一般的です。

辞書型をどの様に使用すると良いのかはAPI仕様書に書いてあります。

まず、辞書型で title を指定すると「タイトル・見出し」が取得できると書いてあります。

print('タイトル：', tenki_data['title'])

続いて、 forecasts を指定すると「予報日ごとの天気予報」が取得できる様です。
ただ、JSON形式に特有の少し複雑な手順が必要なので、一緒に流れを押さえて行きましょう。

print(tenki_data['forecasts'])

まず、forecasts を指定すると最初・最後が [] で囲われているリスト型が表示されました。
ここは取得したいデータに応じて『今日：[0] 、明日：[1] 、明後日[2] 』といったように指定すれば良いと予想ができます。

# 「今日」のデータを指定
print(tenki_data['forecasts'][0])

だいぶスッキリしましたね。ここまで来たら目的に応じて好きなデータを取ってくれば良いので、今回は「予報日：dataLabel、天気：telop」を表示させてみましょう。

# 予報日
print('予報日：', tenki_data['forecasts'][0]['dateLabel'])
# 天気
print('天気：', tenki_data['forecasts'][0]['telop'])

このようにして『API仕様書チェック～リクエスト～レスポンス』の一連手順が流れて行きます。
他にも色々な情報が取得できるので、API仕様書を参考に色々と試されてみて下さい。

さいごに

APIはサービスによって使用方法がバラバラである点が非常に困りものです。
しかし、今回ご紹介した以下をベースに考えていけば、ほとんどのAPIを使いこなすことが可能です。

APIを使用するために必要な情報

Webサービスに接続するための情報（サービス登録時に手に入る）
- API エンドポイント（サービスに接続するためのURL）
- API キー（接続に必要なパスワード）
Webサービスに送信する情報（API仕様書で確認できる。））
- メソッド（主にPOSTかGET）
- クエリパラメータ（使用するAPI・サービスの種類など詳細を指定）
- ヘッダ（データの種類や、API キーなどの認証情報を入力　※POSTメソッドで指定する）
- ボディ（APIと送受信したい情報を入力。※POSTメソッドで指定する）

確認の手順

API エンドポイントは？
API Keyの取得方法は？
POSTかGETか？
クエリパラメータは？
ヘッダ・ボディで送信すべき情報は？

以上で「APIの仕組み・使いこなす方法」は終了です。
皆さんの開発に役立つ情報になれば幸いです。

※SNS でも色々な情報を発信しているので、記事を読んで良いなと感じて頂けたら
Twitterアカウント「Saku731」もフォロー頂けると嬉しいです。

P.S.

「システム企画・要件定義に必要な関係者との調整スキル」 について記事を書きました。３つの観点からコミュニケーションのポイントを整理しています。
ーーー
１）相手の思考タイプ（考え方の特徴）
２）相手の立場（役職・部署）
３）プロジェクトのフェーズ

リンクはこちら：
https://qiita.com/Saku731/items/c43137a6f4bf7166490a
ーーー