Heroku の Platform API を叩いてみる 〜 HeaderのAcceptを使ったAPIバージョン指定

はじめに

この記事は Heroku Advent Calendar 2019 の6日目の記事です。

Heroku Platform API について

Heroku には Platform API （https://devcenter.heroku.com/categories/platform-api）があり、これを叩いてみたので、叩き方や気づいたことを書く。

APIリファレンスは下記ページにあるのだが、非常に充実していて、色々取れる。うまく使えば面白い物が作れそうだ。

• https://devcenter.heroku.com/categories/platform-api

今回の目的

年末で確定申告の時期で、書類を集めなければいけなお。ということで、Invoice（請求書） API を叩いて請求書情報をとる。

• Heroku Platform API v3
• PHP

を使う。

API Token の発行

とりあえず自分が叩ければいいので、quickstart に書いてあるとおりに Heroku CLI を使って Token を発行した。*1 -d にはアプリのDescriptionを入れる。

$ heroku authorizations:create -d "sample-app"
Creating OAuth Authorization... done
Client:      <none>
ID:          7a21bb66-2972-49e0-a9cc-9e820e8f580c
Description: sample-app
Scope:       global
Token:       <ここにトークンが表示されている>
Updated at:  Tue Nov 26 2019 11:20:46 GMT+0900 (GMT+09:00) (less than a minute ago)

https://dashboard.heroku.com/account/applications の Authorizations を見ると、先程のアプリケーションが追加されている。

叩く

PHP で Guzzle を使って叩く。今回は Invoice List API を叩いて領収書一覧をとる。ドキュメントは下記。

• https://devcenter.heroku.com/articles/platform-api-reference#invoice-list

コードがこちら。

<?php

$client = new GuzzleHttp\Client();

$token = 'さっきのトークン';

$response = $this->client->get(
  'https://api.heroku.com/account/invoices', [
  'headers' => [
    // AcceptパラメータでAPIのバージョンを指定する
    'Accept' => 'application/vnd.heroku+json; version=3',
    'Authorization' => 'Bearer ' . $token,
  ],
]);

var_dump(json_decode($response->getBody()->getContents(), true));

簡単にAPIが叩けて請求書情報が返ってくる。((これで得られた請求書の number を使い、先月の請求書をHTML形式で保存することができる。請求書をとってくる部分も一癖あるののだが、この記事では触れない。))

array(19) {
  [0]=>
  array(10) {
    ["charges_total"]=>
    int(0)
    ["created_at"]=>
    string(20) "2019-02-01T03:23:28Z"
    ["credits_total"]=>
    int(-95)
    ["id"]=>
    string(36) "17101b37-c27f-4616-9e92-9b27ca490d9f"
    ["number"]=>
    int(24689937)
    ["period_end"]=>
    string(10) "2019-03-01"
    ["period_start"]=>
    string(10) "2019-02-01"
    ["state"]=>
    int(1)
    ["total"]=>
    int(0)
    ["updated_at"]=>
    string(20) "2019-03-01T22:56:19Z"
  }
  [1]=>
（略）

面白いのは、AcceptヘッダにAPIのバージョンを指定するところだ。GitHubのAPIでも同様のインタフェースになっているが、このパターンのAPIは初めて叩いたので新鮮だった。

PATHに /v3/ って入っていたり、パラメータで version=3 だったりするAPIも多いと思う。

まとめ

• Heroku の Platform API で Invoice の情報をとってみた
• APIのバージョンをHeaderパラメータのAcceptで指定する形式のAPIを叩けた

*1:OAuth認可方式になっている