基礎知識

APIとは何か。仕組み・種類・連携でよくある課題を解説

APIという言葉は日常的に使われますが、何を指すのかは曖昧なまま進むことがあります。この記事では、仕組みから連携時の実務まで、順に説明します。

APIとは何か

APIは、システム同士がやり取りするための窓口です。

たとえば地図を表示したい場合、自分で地図を作る必要はありません。地図サービスのAPIに「この座標の地図をください」と要求すれば、データが返ってきます。

重要なのは、中身を知らなくても使えることです。地図がどう作られているかを理解する必要はなく、決められた形式で要求すれば結果が得られます。

この性質により、システムを部品として組み合わせられるようになりました。決済、認証、通知、配送。多くの機能が、自前で作らずに利用できます。

社内でも同じ考え方が使われます。フロントエンドとバックエンドの間も、APIでつながっています。

RESTという方式

現在最も広く使われている方式がRESTです。

考え方は単純で、扱う対象をURLで表し、操作を種類で指定します。

たとえば `/users/123` というURLは「ID123の利用者」を指します。これに対して、取得（GET）なら情報を返し、更新（PUT）なら書き換え、削除（DELETE）なら消す。

この規則性が、REST方式の利点です。命名の作法が共有されているため、初めて見るAPIでも動作を推測できます。

一方で課題もあります。必要なデータを集めるのに、複数回の要求が必要になる場合です。利用者の情報と、その注文履歴と、各注文の商品を取得するのに3回。通信の回数が増えると、表示が遅くなります。

GraphQLという方式

REST方式の課題に対応する形で登場したのがGraphQLです。

特徴は、必要なデータを1回の要求で指定できることです。「利用者の名前と、注文履歴の日付と、商品名がほしい」と一度に伝えられます。

この方式が向くのは、画面ごとに必要なデータが異なる場合です。モバイルアプリでは通信量を抑えたいため、採用されることがあります。

ただし、すべての場面で優れているわけではありません。サーバー側の実装が複雑になり、キャッシュの扱いも難しくなります。

実務では、RESTが標準でGraphQLが選択肢という位置づけです。案件数はRESTが圧倒的に多くなります。

Webhookとの違い

APIと似た文脈で登場するのがWebhookです。向きが逆という違いがあります。

APIは、こちらから要求して結果を受け取ります。「注文の状況を教えてください」と聞きにいく形です。

Webhookは、相手から通知が来ます。「注文の状態が変わりました」と、変化があった時点で送られてきます。

決済の完了通知、配送状況の更新、外部サービスでの操作。いつ起きるか分からない事象には、Webhookが適しています。

APIで定期的に確認する方式もありますが、頻繁に問い合わせれば負荷がかかり、間隔を空ければ反映が遅れます。Webhookはこの問題を解決します。

認証のしかた

APIは誰でも使えるわけではありません。利用者を確認する仕組みが必要です。

APIキー。あらかじめ発行された文字列を、要求に添えて送ります。単純ですが、漏れると誰でも使えてしまいます。

トークン方式。ログイン時に一時的な許可証を発行し、それを使います。期限があるため、漏洩時の被害を限定できます。

OAuth。他社サービスの情報を、パスワードを預からずに利用する仕組みです。「Googleでログイン」がこれにあたります。

いずれの方式でも、鍵の管理が最大の論点です。プログラムの中に直接書き込んで公開してしまう事故が、実際に多く起きています。

連携で起きる典型的な問題

実務でよく発生する問題を挙げます。

• 仕様書と実際の動作が違う／古い仕様書のまま更新されていない
• 回数の制限がある／一定時間に送れる要求の上限。設計時に確認が必要
• 相手が落ちる／外部サービスが停止したときの動作を決めておく
• 形式が変わる／提供側の仕様変更で、動かなくなる
• データの不整合／こちらの認識と相手の状態がずれる

3つ目と4つ目は、設計段階で対策を決めておくべきです。外部に依存する以上、相手の都合で止まる可能性は常にあります。

止まったときにどうするかを決めていない設計は、必ずどこかで問題を起こします。

発注時に確認すること

API連携を含む案件では、事前に確認すべき項目があります。

仕様書はあるか。存在しない、または古い場合、調査に時間がかかります。見積もりに影響します。

試験用の環境はあるか。本番と別に試せる環境がないと、開発中の検証ができません。

利用の制限は。回数、料金、利用条件。無料枠を超えた場合の費用も確認します。

提供元の連絡先は。問題が起きたときに問い合わせられるか。過去に作った会社と連絡が取れない場合、難易度が上がります。

これらは技術知識がなくても聞ける項目です。商談の段階で確認できると、見積もりの精度が上がります。

APIの設計で気をつけること

提供する側になった場合の要点を整理します。

• 命名を一貫させる／複数形か単数形か、区切り文字。途中で変えない
• 誤りの返し方を統一する／どの状況でどの番号を返すかを決めておく
• 版を管理する／変更時に既存の利用者が壊れないようにする
• 件数を制限する／一度に返す量に上限を設ける。全件返す設計は破綻する
• 文書を実装と同期させる／古い仕様書は、ないより有害な場合がある

3つ目が最も重要です。一度公開したAPIは、利用者がいる限り勝手に変えられません。変更が必要なら新しい版を追加し、旧版を一定期間残すという運用になります。

この制約があるため、最初の設計が長く影響します。

連携案件の進め方

外部システムとの連携を含む案件は、進め方に注意が要ります。

第一に、早い段階で実際に接続してみる。仕様書だけで設計を進めると、想定と違う動作が後から判明します。

第二に、相手が落ちている前提で設計する。応答がない、遅い、誤りを返す。これらの場合にどうするかを決めます。再試行するか、諦めるか、後で処理するか。

第三に、記録を残す。いつ何を送り、何が返ったか。問題が起きたとき、こちらの問題か相手の問題かを切り分ける根拠になります。

第四に、試験環境での確認を契約に含める。本番でしか試せない連携は、危険が大きくなります。