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

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

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

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


こういった悩みを解決するには **どのAPIにも共通する仕組み** を理解すると良いです。
具体的なPythonのコードまで紹介するので、読み終わる頃にはAPIの使い方が身に付いているはずです。
※本記事では「WebAPI」のみ扱います。※API・WebAPIの違いを知りたい方は [こちら](https://techtarget.itmedia.co.jp/tt/news/1806/13/news01.html) 


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

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



**SNS でも色々な情報を発信しているので、記事を読んで良いなと感じて頂けたら**
**[Twitterアカウント「Saku731」](https://twitter.com/digisaku710) もフォロー頂けると嬉しいです**


## APIとは（APIを使うメリット）
APIは「**A**pplication **P**rogramming **I**nterface」の略です。
直訳すると以下の様になります。

- アプリケーション（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仕様書に書いてあるので、最初は意識しなくても大丈夫です。
※違いを詳しく知りたい方は [【こちら】](https://qiita.com/Sekky0905/items/dff3d0da059d6f5bfabf) を参照ください。

なお、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なので実行してもエラーになります。

```py
# ライブラリのインポート
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）にすべての情報を含める**

```py
# ライブラリのインポート
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に似ていますね。
裏側では「①原則」と同じ形でデータ送信されるので結果は同じです。

```py
# ライブラリのインポート
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サービス上で表示させることで、自分で１から開発する手間が省けます。

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/99621a16-20f1-f375-ee3f-b73a87188913.png)

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


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/b96324c7-b832-f9eb-d0b7-d7235c8a3710.png)


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

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

http://weather.livedoor.com/weather_hacks/webservice

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/018ec156-d859-f2cd-419c-7b0e2d9fe80c.png)


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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/6d756458-bea7-e677-bea6-796c7f40e4d3.png)


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


1. **API エンドポイントは？**
http://weather.livedoor.com/forecast/webservice/json/v1
※エンドポイントはURL/URI といった名称で記載されていることがあります。


2. **API Keyの取得方法は？**
特に記述がないので、認証不要（API Key不要）で利用できるサービスのようです。

3. **POSTかGETか？**
このサービスでは**GET**メソッド を使用します。今回の様に仕様書を一見してもメソッドが明記されていないケースでは以下のように判別します。
    - 「エンドポイント（URL）＋クエリパラメータ」の形で使用する記述がある場合：GETの場合が多い
    - それ以外：POSTの場合が多い

4. **クエリパラメータは？**
天気予報を取得したい地域（ `city` ）を指定すれば良いようです。
サンプルで書いてある「久留米：400040」を使用してみましょう。

5. **ヘッダ・ボディで送信すべき情報は？**
GETメソッドを使用するのでヘッダ・ボディは用意する必要ありません。



## Pythonコードサンプル
リクエストに必要な情報が分かったのでPythonでAPIにリクエストを投げてみましょう。

### APIリクエストの送信
コードをコピペしてそのまま実行して頂ければ大丈夫です。

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

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

```py
print(tenki_data)
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/1e54e442-b1de-c9b6-49ed-c7fab0aab377.png)


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

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

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

http://weather.livedoor.com/weather_hacks/webservice

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/07f4a203-2084-4da2-bcec-01e20efc96f3.png)


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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/9bf35326-5016-5228-d389-ecaa29d41da5.png)




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

```py
print(tenki_data['forecasts'])
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/ad1c0551-9c9d-705f-bb12-b8d787b63321.png)


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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/19cd8287-9065-1e85-25c3-fbef9ffa137c.png)

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/555158/1f2de9fe-f9c3-18f1-af16-420b294b4cea.png)



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


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

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

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

**確認の手順**

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




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

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


**P.S.**

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

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