【新卒向け】API入門 - Webサービスの仕組みを理解する

APIはもう毎日使っている

朝、スマホの天気アプリを開いたとします。あのアプリ自身が気象観測をしているわけではありません。気象データを持っているサーバーに「この地点の今の天気を教えて」と問い合わせ、返ってきた数値を画面に描いているだけです。ネットショッピングでカード決済をするときも、そのサイト自身がカードの有効性を検証しているのではなく、決済代行サービスに処理を依頼しています。「Googleでログイン」ボタンも同じ構図で、サイトはGoogleに「この人が本人かどうか確認してほしい」と依頼しています。

この「プログラムが別のプログラムに仕事を依頼する仕組み」がAPIです。つまりAPIは、これから初めて出会う未知の技術ではなく、皆さんが毎日使うアプリの裏側ですでに大量に動いているものです。この記事では、その裏側を手前から順番に見ていきます。

APIの本質は「プログラム用の窓口」

API（Application Programming Interface）とは、プログラムの機能を、決められた形式で外部から呼び出せるようにした窓口のことです。

UI（User Interface）と対比すると輪郭がはっきりします。UIは人間のための窓口で、ボタンやフォームや画面は、人間が見て操作するために作られています。一方APIはプログラムのための窓口で、人間の目には見えませんが、決められた場所（URL）に決められた書式でリクエストを送れば、決められた形式で結果が返ってきます。同じ機能に対する、利用者が違うだけの2つの入口だと考えてください。

重要なのは「決められた形式」という部分です。窓口の場所、依頼の書き方、返事の形は、すべて事前にAPI仕様書として公開されています。だからこそ、作った会社も言語も違うプログラム同士が、お互いの内部実装をまったく知らないまま正確に連携できます。天気アプリと気象サーバーの関係も、ECサイトと決済サービスの関係も、頼りにしているのは相手の仕様書だけです。

土台のHTTPを先に理解する

Web上のAPI（Web API）は、HTTPという通信の約束事の上で動いています。ここを飛ばしてAPIだけ学ぶと後で必ず戻ってくることになるので、先に押さえます。

HTTPの通信は、必ずリクエスト（こちらからサーバーへ）とレスポンス（サーバーからこちらへ）の1往復で完結します。リクエストの主な構成要素は次の3つです。

• URL … どのサーバーの、どの資源に用があるか
• メソッド … その資源をどうしたいか。GET（取得）、POST（新規作成）、PUT（更新）、DELETE（削除）の4つをまず覚えれば十分です
• ヘッダーとボディ … ヘッダーは付帯情報（データ形式や認証情報など）、ボディは送るデータ本体（POSTやPUTで使う）

レスポンス側で最初に見るのはステータスコードという3桁の数字です。処理結果の要約で、200（成功）、404（対象が見つからない）、401（認証されていない）、500（サーバー内部でエラー）の4つを知っていれば当面は困りません。

実はブラウザでWebページを開く行為も、GETリクエストを送ってHTMLというボディを受け取っているだけです。Web APIとの違いは、返ってくる中身が人間向けのHTMLではなく、プログラムが読みやすいデータ形式——多くの場合JSON——である点だけです。

JSONの読み方

JSON（JavaScript Object Notation）は、Web APIの返事で最も広く使われるデータ形式です。構造は3つしかありません。

1. オブジェクト { } … 「名前: 値」のペアの集まり
2. 配列 [ ] … 値を順番に並べたもの
3. ネスト … 値の位置に、さらにオブジェクトや配列を入れられる

実物を1つ読んでみます。

{
  "name": "sato",
  "age": 23,
  "skills": ["Java", "SQL"],
  "department": {
    "name": "開発1課",
    "floor": 5
  }
}

全体が1つのオブジェクトです。name の値は文字列 "sato"、age は数値 23。skills の値は配列で、文字列が2つ並んでいます。department の値はオブジェクトになっていて、その中にまた name と floor がある——これがネストです。コツは外側から1段ずつたどること。どんなに巨大なJSONも、この3構造の組み合わせにすぎません。

実際に叩いてみる

ここまでの知識で、本物のAPIを呼べます。curlというコマンドラインツールを使います（Windows 10以降とmacOSには標準搭載。PowerShellでは curl.exe と入力してください）。相手は、APIキーなしで使える気象データの公開API「Open-Meteo」です。

curl "https://api.open-meteo.com/v1/forecast?latitude=35.68&longitude=139.76&current_weather=true"

リクエストを分解します。

• curl … HTTPリクエストを送るコマンド。メソッドを指定しなければGETになります
• https://api.open-meteo.com … 窓口の場所。Open-MeteoのAPIサーバーです
• /v1/forecast … 「予報」という資源を指すパス
• ? 以降 … クエリパラメータ。latitude と longitude は東京駅付近の緯度経度、current_weather=true は「現在の天気も含めて」という指定です

実行すると、次のようなJSONが返ってきます（抜粋）。

{
  "latitude": 35.7,
  "longitude": 139.75,
  "current_weather": {
    "temperature": 28.3,
    "windspeed": 8.6,
    "weathercode": 1,
    "time": "2026-07-01T03:00"
  }
}

前の章の読み方どおり、外側から current_weather → temperature とたどると、気温28.3度が取り出せます。天気アプリが画面に表示している「28℃」の正体は、まさにこの数値です。冒頭で見た裏側を、いま自分の手で再現したことになります。

認証の初歩 - なぜ鍵がいるのか

Open-Meteoは誰でも使える公開APIでしたが、実務で扱うAPIの多くは「誰からのリクエストか」を確認します。理由は主に3つ。ユーザー個人のデータを本人以外に渡さないため、利用量の制限や課金を利用者ごとに行うため、そして不正利用があったときに追跡するためです。

最も単純な仕組みがAPIキーです。サービスから発行された長いランダム文字列を、リクエストのヘッダーに添えて送ります。

curl -H "Authorization: Bearer sk_XXXXXXXX" "https://api.example.com/orders"

APIキーはパスワードと同じ重さで扱ってください。公開リポジトリにキーをうっかりコミットしてしまう事故は毎年繰り返されており、漏れたキーは短時間でクローラーに拾われます。結果として、他人があなたの課金枠でAPIを乱用したり、キーの権限次第では顧客データにアクセスされたりします。キーをコードに直接書かず、環境変数や秘密情報管理の仕組みに置くのが基本です。

エラーと付き合う

APIを使っていればエラーは日常です。ステータスコードの先頭1桁を見ると、「どちら側の問題か」の見当がつきます。

• 4xx（クライアントエラー） … まず自分のリクエストを疑います。URLの打ち間違い（404）、認証情報の不足や誤り（401）、パラメータの形式違反（400）など。原因が自分側にある以上、同じリクエストを何度送り直しても結果は変わりません
• 5xx（サーバーエラー） … 相手側の問題です。自分のリクエストが正しくても起こります。一時的な障害のことも多いので、時間を置いて再送（リトライ）する価値があるのはこちらです

リトライには作法があります。間隔を空けながら、回数は数回まで。障害中のサーバーに全クライアントが即座に再送を繰り返すと、負荷が積み上がって復旧をさらに遅らせるからです。

RESTという言葉に出会ったら

API仕様書やコードレビューで、いずれ必ず「REST」という言葉に出会います。RESTは厳密な規格というより設計スタイルで、核にあるのはリソース指向という考え方です。操作したい対象（リソース）を名詞としてURLで表し、それをどうするかはHTTPメソッドで表します。

• GET /users/42 … 42番のユーザーを取得する
• DELETE /users/42 … 42番のユーザーを削除する

「名詞はURL、動詞はメソッド」という役割分担が守られたAPIは、初見でも意味を推測できます。この記事で見てきたURL・メソッド・ステータスコード・JSONの知識は、そのままRESTの読み書きに直結します。

まとめ

道筋を振り返ります。APIは「プログラム用の窓口」であり、Web APIはHTTPの1往復で動き、返事はJSONの3構造で読める。認証は鍵の管理まで含めて自分の責任で、エラーは先頭1桁で切り分ける——これだけで、API仕様書を読む入口には立てています。まずはcurlで公開APIを1回叩き、返ってきたJSONを外側から1段ずつたどってみてください。普段使っているアプリの裏側が見えると、日々の開発で扱う技術の解像度が一段上がります。