835
946

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

Last updated at Posted at 2020-01-03

株式会社デジサク がお送りするプログラミング記事、
今回は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から開発する手間が省けます。

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

image.png

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

image.png

APIサービスの例

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

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

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

image.png

API仕様書を見てみる

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

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

image.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リクエストの送信

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

# 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)

image.png

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

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

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

image.png

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

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

image.png

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

print(tenki_data['forecasts'])

image.png

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

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

image.png

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

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

image.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」 もフォロー頂けると嬉しいです。

P.S.

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

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

835
946
7

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
835
946