株式会社デジサク がお送りするプログラミング記事、
今回は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の利点が分かったところで、その仕組みを理解して行きましょう。
大きく分けて3つの知識が必要となります。
- 1)Webの仕組み
- 2)HTTPリクエスト
- 3)HTTPレスポンス
1)Webの仕組み
普段から何気なく使っているインターネットはWebのおかげで成り立っています。
Webは『インターネット上で文章や画像など、あらゆる種類のデータを送る仕組み』です。
なので、APIで他の人が作ったWebサービスを借りてくるには当然ながらWebの理解が必要です。
Webを理解するためには以下3つを押さえましょう。
- HTTP(Hyper Text Transfer Protocol)
- URL(正確にはURI)
- ハイパーテキスト(HTMLなど)
文章で整理するとこういった具合です。
Webとは、、
『HTTPという通信の約束に従って』
『URLで指定する場所(サーバー)との間で』
『ハイパーテキスト(情報)をやり取りする』ための仕組み。
Webを詳しく理解するためには何冊も本を読まないといけないですが、
「URLで指定したサーバーと情報のやり取りを行う技術」だと理解すれば十分です。
このWeb技術を使用して自分のWebサービスと**他の人が作ったWebサービス(サーバー)**の間で簡単に情報のやり取りを実現する仕組みがAPIなのです。
そして、具体的にAPIを使いこなすには、Webが採用しているHTTP(通信上の約束事)を使用する必要があります。「相手へ情報を送信するHTTPリクエスト」と「相手から情報を受け取るHTTPレスポンス」の2種類があるので以降で理解して行きましょう。
2)HTTPリクエスト
まず自分から相手にデータを送信するHTTPリクエストです。
API経由で**他の人が作ったWebサービスに「機能を使わせて下さい」**といったリクエストを投げる処理です。
WebサービスごとにAPIの使い方が異なって見えるのですが共通する基礎があります。
どんなAPIを使うときでも共通して以下の情報を用意すれば良いです。
- Webサービスに接続するための情報(サービス登録時に手に入る)
- API エンドポイント(サービスに接続するためのURL)
- API キー(接続に必要なパスワード)
- Webサービスに送信する情報(APIの仕様書で確認できる)
- メソッド(主にPOSTかGET)
- クエリパラメータ(使用するAPI・サービスの種類など詳細を指定)
- ヘッダ(データの種類や、API キーなどの認証情報を入力 ※POSTメソッドで指定する)
- ボディ(APIと送受信したい情報を入力。※POSTメソッドで指定する)
これらの大項目はどんなAPIでも共通なのですが、細かな内容で違いが出てきます。
各サービスが公開している「API仕様書」で必要な内容を確認しましょう。
※慣れるまではQiitaに投稿されているサービス利用手順を読むのが1番おススメです。
各地の天気を取得できる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)
3)HTTPレスポンス
API経由でWebサービスにHTTPリクエストを送ると、HTTPレスポンスという『返事』が送られてきます。
この『返事』を自分のWebサービス上で表示させることで、自分で1から開発する手間が省けます。
例えば、、
『リクエスト:天気を教えてください。今日, 日本, 東京』
『レスポンス:晴れのち曇りです』
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.
「システム企画・要件定義に必要な関係者との調整スキル」 について記事を書きました。3つの観点からコミュニケーションのポイントを整理しています。
ーーー
1)相手の思考タイプ(考え方の特徴)
2)相手の立場(役職・部署)
3)プロジェクトのフェーズ
リンクはこちら:
https://qiita.com/Saku731/items/c43137a6f4bf7166490a
ーーー