- APIが何をしているか
- リクエストとレスポンスの流れ
- JSONとWebhookの役割
- APIキーとOAuthの違い
- 会社でキーを管理する決めごと
結論
APIは、あるソフトやサービスが「外のプログラムからは、この形で頼めば、この形で答えます」と用意している窓口です。人が画面を操作する代わりに、プログラム同士が決まった形でやりとりします。
会社でAPIを使うとき、技術の細かい話より先に考えることが2つあります。1つは「APIキーなどの鍵を、誰がどこで管理するか」、もう1つは「回数や料金の上限がどうなっているか」です。連携が便利になる一方で、困る場面の多くはこの2つから起きます。
APIとは何か
飲食店にたとえると、APIは「注文票」にあたります。お客さんは厨房に入って料理を作るのではなく、決まった書き方の注文票を出して、料理を受け取ります。厨房の中でどう作っているかを知らなくても、注文票の書き方さえ合っていれば料理は出てきます。
ソフトウェアでも同じです。たとえば、次のような連携の裏側でAPIが使われています。
- ネットショップで注文が入ると、在庫管理のシステムの在庫数が自動で減る
- 勤怠システムの集計結果を、給与ソフトが読み込む
- 自社のサイトに、地図サービスの地図を表示する
- 会計ソフトが、銀行口座の入出金の明細を取り込む
どれも、人が片方の画面からデータを書き写し、もう片方に入力していた作業を、プログラム同士のやりとりに置き換えたものです。AIが別のサービスを操作するときも、多くはAPIを通じて動いています。
APIは「Application Programming Interface」の略です。Interfaceは「接点」「窓口」という意味で、プログラムのための窓口、と読むと意味をつかみやすくなります。
やりとりの基本：リクエストとレスポンス
APIのやりとりは、基本的に「頼む」と「答える」の1往復です。
- リクエスト：使う側が送る依頼。「この商品の在庫数を教えて」「この注文を登録して」
- レスポンス：サービス側からの返事。「在庫は12個です」「登録しました」「その商品は見つかりません」
リクエストには、どこに頼むか（URLの形をした宛先。エンドポイントと呼びます）、何をしたいか（読む・登録する・変える・消す）、必要なデータを入れます。うまくいかなかったときは、レスポンスに「見つからない」「権限がない」「回数の上限を超えた」といった理由が、番号付きで返ってきます。連携が止まったときは、まずこの番号と理由を見るのが調べる出発点です。
RESTという考え方
ウェブのAPIでよく使われている設計の考え方に、RESTがあります。細かい定義はここでは触れませんが、実務で目にするのは「URLで対象を表し、読む・登録する・変える・消すといった操作の種類を分けて送る」という形です。たとえば「/orders/1001」という宛先に「読む」を送れば注文1001番の内容が返り、「変える」を送れば内容が更新される、というイメージです。
JSONというデータの書き方
リクエストやレスポンスの中身は、JSONという形式で書かれていることが多くあります。JSONは、「項目の名前」と「値」を組にして並べる書き方で、{"注文番号": 1001, "顧客名": "山田商店"} のような形をしています。
表の形のCSVとの違いは、入れ子にできることです。1件の注文の中に複数の商品の明細を持たせる、といった表では書きにくいデータも、そのまま表せます。CSVは人が表として見たり受け渡したりするのに向き、JSONはプログラム同士の受け渡しに向いた形、と考えてください。
Webhook：向こうから知らせてもらう仕組み
APIは基本的に「こちらから聞きに行く」仕組みです。新しい注文が入ったかを知りたければ、定期的に「新しい注文はある？」と聞き続けることになります。
Webhookはその逆で、「注文が入ったら、このURLに知らせてください」と先に登録しておくと、出来事が起きたときに向こうから知らせが届きます。たとえば「問い合わせフォームに送信があったら、社内のチャットに通知する」といった連携は、Webhookでよく作られます。
| 見るところ | APIに聞きに行く | Webhook |
|---|---|---|
| やりとりを始める側 | 使う側 | サービス側 |
| 向いている場面 | 必要なときにデータを取る | 出来事をすぐ知りたい |
| 気をつけること | 聞きすぎると回数の上限に当たる | 受け取る窓口を用意し、守る必要がある |
Webhookを受け取るURLは、外から届く場所に置くことになります。本当にそのサービスからの知らせかを確かめる仕組み（署名の確認など）が用意されているかを、使う前に見ておきます。
認証：APIキーとOAuth
APIは誰でも好きに使えるわけではありません。「あなたは誰か」「何をしてよいか」を確かめる仕組みがあります。
APIキー
APIキーは、サービスが発行する長い文字列で、リクエストに付けて送ります。合言葉に近いもので、キーを持っていれば、そのキーに許された操作ができます。つまり、キーが漏れると、他人がこちらのふりをしてAPIを使えてしまいます。使った分だけ料金がかかるサービスなら、その請求もこちらに来ます。
OAuth
OAuthは、パスワードを渡さずに、別のアプリに「一部の操作だけ」を許す仕組みです。あるアプリを使い始めるときに、「このアプリに、カレンダーの閲覧を許可しますか？」という確認画面が出ることがあります。あれがOAuthのよくある場面です。パスワードそのものは相手に渡らず、許した範囲の操作だけができる許可証が発行されます。許可は、あとから取り消すこともできます。厳密には「誰か」を確かめる認証より、「何をしてよいか」を決める認可のための仕組みです。
料金と回数制限の考え方
多くのAPIには、使える回数や量に上限があります。「1分間に何回まで」「1か月に何件まで」といった形です。上限を超えると、しばらくエラーが返ったり、追加の料金がかかったりします。
料金の形もさまざまです。一定の回数までは無料で、それを超えると使った量に応じてかかるもの、月額の契約に含まれているもの、有料の契約でないと使えないものなどがあります。具体的な上限や料金はサービスごとに違い、変わることもあるので、各サービスの公式の案内を確認してください。
実務で気をつけたいのは、プログラムの間違いで同じリクエストを大量に送ってしまう場合です。上限に当たって連携が止まる、使った量に応じた料金なら想定していない請求になる、といったことが起こりえます。利用額の上限や、使いすぎたときの通知を設定できるサービスなら、使い始める前に設定しておきます。
会社で使うときの注意
APIの連携は、一度作ると「動いていて当たり前」になり、誰が作ったのか忘れられがちです。次の点を最初に決めておきます。
- キーを置く場所を決める：APIキーを、チャット、メール、共有の表計算ファイル、プログラムの中に直接書かない。パスワード管理のツールや、システムが用意している秘密の情報の保管場所に置きます。
- 用途ごとにキーを分ける：1つのキーを複数の連携で使い回すと、漏れたときにどこから漏れたのかわからず、止めると全部が止まります。
- 必要な権限だけにする：読むだけでよい連携には、読むだけのキーを発行します。
- 持ち主を会社にする：担当者の個人のアカウントで契約やキーの発行をしていると、その人が異動や退職をしたときに管理できなくなります。
- 一覧を作る：どのサービスとどのサービスが、どのキーでつながっていて、誰が管理しているかを表にしておきます。
- 漏れたら無効にして作り直す：キーが漏れた疑いがあれば、そのキーを無効にし、新しいキーに差し替えます。
例として、5人の事務所で、ネットショップの注文を会計ソフトへ送る連携を、外部の人に作ってもらったとします。キーがその人の手元のメモにしかなく、会計ソフトの契約も担当者の個人名だった場合、担当者が辞めた時点で、止まった連携を誰も直せなくなります。キーの保管場所と契約の名義を会社側にしておくだけで、この事態は避けられます。
また、APIは提供する側の都合で仕様が変わったり、古い形が使えなくなったりすることがあります。サービスから届く変更のお知らせを受け取る人を決めておくと、ある日突然連携が止まって慌てる、ということを減らせます。
まとめ
APIは、プログラム同士が決まった形で頼み、答えるための窓口です。やりとりはリクエストとレスポンスの1往復が基本で、中身はJSONで書かれることが多く、向こうから知らせてもらうときはWebhookを使います。使う資格はAPIキーやOAuthで確かめられ、回数や料金には上限があります。会社で使うなら、キーの保管場所、権限、契約の名義、連携の一覧を先に決めておいてください。