料金表・資料ダウンロード
クラウドPBX/CTI BIZTEL
2026.05.13
業務改善の第一歩を学ぶ 【第3章】APIリファレンスの読み方を学ぼう！
「BIZTEL」では多彩なAPI群を用意しており、柔軟なシステム連携によるコールセンター運営のサポートが可能です。また、BIZTELブログで掲載中の「BIZTEL API使ってみた」シリーズでは、担当者がAPI連携を活用した様々な機能実装にチャレンジし、センター運営の新たな可能性を拡げる活動をしています。
ですが、「そもそもAPIって？」「なんだか難しそう…」と思う方も多いのではないでしょうか。
そこで、この「業務改善の第一歩を学ぶ」シリーズでは、「BIZTEL API使ってみた」の記事で数々の機能実装に挑戦している田中 美穂さんが、APIの基礎から応用までわかりやすく解説します。
今回は、【第3章】APIリファレンスの読み方を学ぼう！ です。
目次
はじめに
こんにちは！BIZTEL開発部門の田中です。
この記事をご覧いただき、ありがとうございます！
第1章で、API（Application Programming Interface）とは「異なるソフトウェアやシステムが互いに通信し、データや機能をやり取りするための仕組み」であることをお話ししました。
また、第2章では「クライアント」と「サーバー」が重要な役割を担っていることやリクエストとレスポンスの流れ、さらにAPIメソッドの種類などの概要をお伝えしました。
今回の第3章では、「APIリファレンス（説明書）の読み方」を解説していきます。
新しいツールのインストールは不要で、ブラウザだけで進められます。
では、一緒に学んでいきましょう！
APIリファレンスとは
APIリファレンスとは、「APIの使い方（仕様）など、必要な情報が詳しく書かれた説明書」のようなものです。
家電製品を操作する時も、取扱説明書をみながら操作しますよね。
APIも同じように「APIリファレンス」という取扱説明書があるのです。
APIを効果的に利用するには、APIリファレンスを正しく把握することが重要です。まずは、リファレンスに記載されている基本要素について理解していきましょう。
◼︎APIリファレンスの基本要素
APIリファレンスには、主に以下の情報が記載されています。まずは、これらの基本要素を把握することからはじめましょう。
今すぐに全てを覚える必要はありません！「APIの説明書にこれらの項目がある」ということだけ知っておけばOKです！
| カテゴリ | 用語 | 意味 | 例 |
| リクエスト | リクエストURL （必須） |
APIリクエストを送信するための完全なURL | https://api.openai.com/v1/chat/completions |
| 認証情報 （多くは必須だが、認証なしの場合もある） |
APIを利用する際に必要な認証キーやトークン |
Authorization: Bearer YOUR_API_KEY | |
| メソッド （必須） |
APIリクエストの種類を示すラベル | GET・POST・PUT・DELETE など | |
| リクエストヘッダ （必須） |
リクエストを送信する際に含める必要のある追加情報 | Content-Type: application/json | |
| リクエストボディ （メソッドがGETの場合など、指定なしのケースもある） |
データの追加や更新時に必要な情報など、リクエスト内容を記載する |
{ "param1": "value1", "param2": "value2" } | |
| レスポンス | レスポンス | APIから返される応答の形式や内容 APIによって、JSON・XMLなど形式は異なる |
{ "status": "success", "data": [...] } |
APIリファレンスの理解を深めよう
「東京都オープンデータAPI」を例に基本要素を確認
APIリファレンスの基本要素の理解を深めるために、第2章のAPIを使ってみようで使用した「東京都オープンデータAPI」を例として見ていきましょう。
◼︎リクエストURLの構造
以下は、第2章で使用した「リクエストURL」の一例です。
東京都オープンデータAPIのリクエストURLは、BaseURL（赤文字）とエンドポイント（青文字）とクエリパラメータ（紫文字）で構成されています。
リクエストURLの構造を理解するためには、この「BaseURL」「エンドポイント」「クエリパラメータ」について把握しておく必要があります。
|
項目 |
意味 |
例 |
|
BaseURL |
API全体の共通部分となるURLです。すべてのエンドポイントの基礎となります。 |
https://api.data.metro.tokyo.lg.jp/v1 |
|
エンド |
BaseURLに続く、アクセスしたい特定のリソースやアクションを指定する部分です。 |
/Event |
|
クエリパラメータ |
リクエストに追加情報を提供するキーと値のペア。エンドポイントの後の「?」に続きます。 |
ex:参加条件.ex:料金_要否=0 |
※1 クエリパラメータが必要かどうかは、APIによって異なります。必ずAPIリファレンスを確認してください。今回の東京都のオープンデータAPIでは、検索条件を絞り込むために使用しています。
東京都オープンデータAPIの実行画面にも、「BaseURL」「/●●●（エンドポイント）」の情報が表示されています。
【補足】URLに表示される文字列はなぜ違う？－ URLエンコードについて －
東京都オープンデータAPIを実行して表示されたリクエストURLを見て、「あれ？」と思った方もいるかもしれません。
⚫︎クエリパラメータに指定した値
「ex:参加条件.ex:料金_要否=0」
⚫︎実際にブラウザのURLに表示された値
「ex%3A%E5%8F%82%E5%8A%A0%E6%9D%A1%E4%BB%B6.ex%3A%E6%96%99%E9%87%91_%E8%A6%81%E5%90%A6=0」
リクエストURL内のエンドポイントの後の「？」に続く、クエリパラメータの文字列が異なっています。ですが、中身は同じです。
これは「URLエンコード」と呼ばれる自動変換によるものです。
インターネットのURLには、日本語や一部の記号（例えば「:」など）は、そのまま使えない決まりがあるため、ブラウザやAPIツールが自動的に変換しています。
例えば、手紙を海外宛に送る時、日本語で記載された宛名では届けることができません。アルファベットなどに変換して書く必要がありますよね。
「URLエンコード」もこれと同じ仕組みです！
ただし、自分で変換する必要はありません。ブラウザやAPIツールが自動的に変換してくれます。
（参考）変換の対応例
|
変換前 |
変換後 |
|
： |
%3A |
|
料金 |
%E6%96%99%E9%87%91 |
|
ex:参加条件.ex:料金_要否=0 |
ex%3A%E5%8F%82%E5%8A%A0%E6%9D%A1% |
基本要素のまとめ
「東京都オープンデータAPI」の場合
第3章で紹介した「東京都オープンデータAPI」を基本要素に当てはめると、以下のようになります。
|
用語 |
設定値 |
|
リクエストURL |
https://api.data.metro.tokyo.lg.jp/v1/Event?ex%3A参加............ |
|
認証情報 |
なし |
|
メソッド |
GET |
|
リクエスト |
Content-Type: application/json |
|
リクエスト |
なし |
|
レスポンス |
JSON形式で返されます。 |
第2章では「Try it out」ボタンを押して、パラメータを入力して「Execute」を押しただけですが、裏側ではこの基本要素に沿ったリクエストが送信されていました。
第3章の振り返り
- APIリファレンスとは
- APIリファレンスは、APIの使い方が詳しく書かれた説明書です。
- APIリファレンスの基本要素
- APIリファレンスには、「リクエストURL」「認証情報」「メソッド」「リクエストヘッダ」「リクエストボディ」「レスポンスの形式や内容」といった基本要素が記載されています。
- リクエストURLの構造
- リクエストURLは、BaseURL ＋ エンドポイント ＋ クエリパラメータで構成されています。
- URLエンコード
- 日本語や記号は、URL上で自動的に変換（URLエンコード）されますが、中身は同じです。変換は自身で行う必要はありません。
- 具体例：東京都オープンデータAPIの利用
- 第2章で体験した「東京都オープンデータAPI」を基本要素に当てはめて、APIリファレンスの読み方を確認しました。
まとめ
第3章では、APIリファレンスの基本要素と読み方について学びました。
「東京都オープンデータAPI」を例に、リクエストURLの構造やURLエンコードについても学びました。
次の第4章では、Postmanを使って生成AI（OpenAI）のAPIを実行する方法を見ていきましょう。
