JavaでAPIを使う方法：基礎からHTTP通信の実装まで

しかし「api java」で検索すると、同じ“API”でも意味が混ざりやすいです。そこで本記事では、まずJavaのAPI（ライブラリの呼び出し口）と、Web API（HTTPで呼ぶ外部サービス）を整理します。さらに、JavaでWeb APIを安全に呼び出すための実務の型（タイムアウト、例外、認証、ログ）までまとめます。なお、本記事執筆時点（2025年12月）では、標準機能でのHTTP通信も選択肢として十分実用的です。

また、社内開発や保守運用では「とりあえず叩けた」だけでは不十分です。したがって本記事は、サンプルコードに加えて運用で困らない判断軸も添えます。まず概念を押さえ、次に実装へ進む流れで読んでください。もしJavaの基礎用語から確認したい場合は、Javaの基礎まとめも併せて参照すると理解が早まります。

APIとは何か：Javaの「API」とWebの「API」を切り分ける

まずAPIは、機能やデータを外部から利用するための仕様・窓口です。例えば「このURLにGETすると、この形式でJSONが返る」といった取り決めもAPIです。さらに政府のガイドでも、APIは導入後の周知や仕様変更通知、運用監視が重要だと整理されています。一次情報としてAPI導入実践ガイドブックも参考になります。

一方で、Javaの文脈では「Java API」という言い方が、標準ライブラリや外部ライブラリのクラス群を指すこともあります。つまり“API”は、文脈によって意味が変わります。そこで、よくある混同をここで分けます。

• さらに、Java標準/外部ライブラリのAPI（例：StringやList、HttpClientなど）を理解したい
• 一方で、JavaでWeb APIを呼び出したい（REST API、JSON、認証など）

したがってこの記事はWeb APIをJavaから呼び出すことを主軸にしつつ、混乱しやすい用語を最初に整えます。もし「そもそもAPIってIT用語として何？」を噛み砕いて読みたい場合は、APIの用語解説ページを先に読むのもおすすめです。

JavaでWeb APIを呼ぶ基本：HTTPメソッド・URL・ヘッダー

例えばWeb API呼び出しは、基本的に「メソッド」「エンドポイントURL」「ヘッダー」「ボディ」で構成されます。さらにレスポンスとして、ステータスコード（200/400/401/500など）と本文（JSON等）を受け取ります。つまり、API連携は“HTTPのルール”を守る作業でもあります。

そのため実装前に、最低限ここを確認すると手戻りが減ります。特に認証方式は最初に詰めるべきです。なぜなら、認証が曖昧だと疎通確認の段階で止まりやすいからです。

• さらに、エンドポイントURL（例：/v1/users など）
• しかし、HTTPメソッド（GET/POST/PUT/DELETE）
• さらに、認証方式（Bearerトークン、APIキー、Basicなど）
• 一方で、入力/出力の形式（JSON、フォーム、URLクエリなど）
• したがって、失敗時の戻り（エラーコード、エラーレスポンス形式）

また、実務では“成功時の仕様”より“失敗時の仕様”の方が重要になります。例えば、同じ400でも「必須パラメータ不足」なのか「形式不正」なのかで対応が変わります。そこで、エラーレスポンスの形式（message/code/detailsなど）も先に確認しておくと、実装が安定します。

実務で先に決めたい「エラー設計」と「ログ」

しかし“つながる”だけで満足すると、運用で詰まります。そこで、例外やエラーを仕様として扱うのがコツです。例えば次の方針を決めておくと、保守が楽になります。

• 例えば、タイムアウトは何秒か（接続・読み取り）
• さらに、再試行する条件（5xxのみ、429のみ等）
• 一方で、認証失敗（401/403）は即時失敗にする
• したがって、ログに残す最小情報（URL、ステータス、相関ID）

さらに、ログは“情報を盛る”ほど良いわけではありません。なぜなら、個人情報や機密情報が混ざると事故になるからです。したがって、ログに残すのは「どのAPIに」「いつ」「どんな結果だったか」が追える最小単位に絞り、必要に応じてマスキングを行います。

Java標準のHttpClientでAPIを呼び出す（GET/POST例）

さらに、Javaには標準のHTTPクライアントとしてjava.net.httpが用意されています。公式のAPIリファレンスも確認できます。java.net.http（公式）

まずはGETでJSONを取得する最小例です。ここではタイムアウトとステータスコード判定までを含めます。なお、社内でHTTPクライアントの方針を統一したい場合は、HttpClientの使い方まとめのように“社内標準”ページを作っておくとレビューが楽になります。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ApiGetExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com/api/v1/users"))
                .timeout(Duration.ofSeconds(10))
                .header("Accept", "application/json")
                .GET()
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        int status = response.statusCode();
        if (status >= 200 && status < 300) {
            System.out.println(response.body());
        } else {
            throw new RuntimeException("API failed. status=" + status + " body=" + response.body());
        }
    }
}

次にPOSTでJSONを送る例です。さらに認証が必要なAPIでは、Authorizationヘッダーの付与が最初のポイントになります。ここで詰まった場合は、API側の仕様（トークンの形式、期限、スコープ）を確認してください。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ApiPostExample {
    public static void main(String[] args) throws Exception {
        String token = "YOUR_TOKEN";
        String jsonBody = "{\"name\":\"taro\",\"role\":\"admin\"}";

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com/api/v1/users"))
                .timeout(Duration.ofSeconds(10))
                .header("Accept", "application/json")
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + token)
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 201) {
            System.out.println("Created: " + response.body());
        } else {
            throw new RuntimeException("API failed. status=" + response.statusCode() + " body=" + response.body());
        }
    }
}

よくある落とし穴：タイムアウト未設定・文字コード・リトライ

しかしAPI連携の不具合は、コードより“設定不足”が原因になりがちです。そこで次の観点でチェックすると事故が減ります。特にタイムアウトは、未設定のままだと“止まって見える”障害になりやすいです。

• しかし、タイムアウト未設定でハングする（接続/読み取りを分けて設定）
• さらに、レスポンスの文字コードや圧縮を想定していない
• 一方で、429（レート制限）や5xxで無限リトライしてしまう
• したがって、再試行回数と待機（指数バックオフ）を設計する

また、HTTPステータスの扱いはチームで揃えると強いです。例えば「4xxは呼び出し側の修正」「5xxは相手側の障害」と切るだけでも、一次切り分けが速くなります。もし社内記事があるなら、HTTPステータスコードの整理として内部リンク化しておくと便利です。

APIを“運用できる形”にする：仕様変更通知・バージョン管理

さらにAPIは、作って終わりではありません。政府のガイドでも、導入時の情報提供や導入後のモニタリング、そして仕様変更の周知が重要と整理されています。一次情報としてAPI導入実践ガイドブックを参照してください。

したがって利用側（Javaアプリ）としても、次を前提にしておくと強いです。ここは“実装”というより“設計”の領域です。

• 例えば、APIバージョン（/v1、/v2）をURLやヘッダーで明示する
• さらに、破壊的変更が来ても検知できるようにレスポンス検証を入れる
• 一方で、障害時に追える相関ID（リクエストID）をログに残す
• そのため、外形監視（定期GET）やメトリクスで早期検知する

また、企業のクラウド活用が進む中で、API連携の数は増えがちです。総務省の「通信利用動向調査（令和6年・企業編）」はe-Statで公開されており、クラウド利用状況などの把握に使われます。一次情報としてe-Stat（通信利用動向調査）も参照できます。

さらに、API連携は“担当者が変わった瞬間”に壊れやすいです。そこで、仕様書の置き場所、変更履歴、連絡先をまとめたページを作り、運用の属人化を減らすのが定石です。

まとめ：JavaでAPIを扱う最短ルート

最後に、要点を3つに絞ります。ここだけでも押さえると、API連携のトラブルが減ります。

• しかし「API」は、JavaのライブラリAPIとWeb APIで意味が分かれるため、最初に切り分ける
• さらに、Java標準のjava.net.httpでGET/POSTは実装でき、タイムアウトとエラー判定が実務の肝
• したがって、認証・再試行・ログ・仕様変更を“運用設計”として先に決める