TypeScriptでAPIレスポンスをインターフェースで定義する方法を徹底解説！初心者にもわかる型定義の基本

1. APIレスポンスとは？

1. APIレスポンスとは？

まず、APIレスポンスとは、Webサービスやサーバーがクライアント（アプリやブラウザ）からのリクエストに対して返すデータのことです。たとえば、天気予報アプリで「今日の天気」を取得するとき、アプリはサーバーに「今日の天気を教えて」とリクエストを送り、サーバーが「晴れ・最高気温25度」といった情報を返してくれます。この返ってきたデータがAPIレスポンスです。

多くの場合、APIレスポンスはJSON形式というデータ形式で返されます。JSON（ジェイソン）とは「JavaScript Object Notation（ジャバスクリプト・オブジェクト・ノーテーション）」の略で、人間にもコンピュータにも読みやすい構造をしています。

2. TypeScriptでAPIレスポンスを安全に扱うには？

2. TypeScriptでAPIレスポンスを安全に扱うには？

JavaScriptでは、APIから受け取ったデータを自由に扱えますが、間違ったプロパティ名を使ってもエラーにならないという欠点があります。たとえば、レスポンスにuserNameがあるのに、usernameと書いても気づかないままエラーが起きてしまうことがあります。

そこで役立つのがTypeScriptのインターフェース（interface）です。インターフェースを使えば、「APIのデータはこの形で来る」という約束をプログラムに教えてあげられます。

3. APIレスポンスをインターフェースで定義する基本例

3. APIレスポンスをインターフェースで定義する基本例

たとえば、ユーザー情報を取得するAPIが次のようなデータを返すとします。

{
    "id": 1,
    "name": "田中太郎",
    "email": "taro@example.com"
}

このデータをTypeScriptで扱うとき、次のようにインターフェースを定義します。

interface UserResponse {
    id: number;
    name: string;
    email: string;
}

これで、TypeScriptに「このデータはidが数字で、nameとemailが文字列だよ」と教えたことになります。

次に、このインターフェースを使ってAPIレスポンスを受け取るコードを書いてみましょう。

async function fetchUser(): Promise<UserResponse> {
    const response = await fetch("https://example.com/api/user");
    const data: UserResponse = await response.json();
    return data;
}

fetchUser().then(user => {
    console.log(user.name); // 正しく補完される！
});

このように、Promise<UserResponse>と書くことで、「この関数はUserResponse型のデータを返すよ」と宣言しています。これにより、TypeScriptがデータの中身を補完してくれるため、ミスを防ぐことができます。

4. ネストしたAPIレスポンスを定義する方法

4. ネストしたAPIレスポンスを定義する方法

現実のAPIでは、もっと複雑なデータ構造を持つこともあります。たとえば、ユーザーの中に「住所情報」が含まれているケースです。

{
    "id": 1,
    "name": "田中太郎",
    "email": "taro@example.com",
    "address": {
        "city": "東京",
        "zip": "100-0001"
    }
}

このような場合も、入れ子構造（ネスト構造）でインターフェースを定義できます。

interface Address {
    city: string;
    zip: string;
}

interface UserResponse {
    id: number;
    name: string;
    email: string;
    address: Address;
}

このように複数のインターフェースを組み合わせることで、APIレスポンス全体をしっかりと型で表現できます。

5. オプショナルプロパティを使って柔軟に定義する

5. オプショナルプロパティを使って柔軟に定義する

APIによっては、必ずしもすべての項目が返ってくるわけではありません。たとえば、emailが登録されていない場合もあるかもしれません。そんなときに便利なのがオプショナルプロパティ（?）です。

interface UserResponse {
    id: number;
    name: string;
    email?: string; // ある場合とない場合がある
}

このように?を付けると、「このプロパティはあってもなくてもいい」という意味になります。APIによってレスポンスが少し違っても、エラーを防げる便利な仕組みです。

6. 実践！配列を含むAPIレスポンスの定義

6. 実践！配列を含むAPIレスポンスの定義

最後に、複数のユーザー情報をまとめて返すAPIの例を見てみましょう。たとえば、次のようなJSONが返ってくるとします。

{
    "users": [
        { "id": 1, "name": "田中太郎", "email": "taro@example.com" },
        { "id": 2, "name": "佐藤花子", "email": "hanako@example.com" }
    ]
}

この場合、インターフェースは次のように定義します。

interface User {
    id: number;
    name: string;
    email: string;
}

interface UsersResponse {
    users: User[];
}

そして、このインターフェースを使って実際にAPIデータを扱うと、次のようになります。

async function fetchUsers(): Promise<UsersResponse> {
    const response = await fetch("https://example.com/api/users");
    const data: UsersResponse = await response.json();
    return data;
}

fetchUsers().then(res => {
    res.users.forEach(user => console.log(user.name));
});

このようにインターフェースを使えば、APIレスポンスを安全に扱えるだけでなく、エディタの補完機能も活用できて、開発効率が格段にアップします。

まとめ

まとめ

TypeScriptでAPIレスポンスを安全に扱うための型定義について振り返ると、インターフェースという仕組みがどれほど重要な役割を果たすかがよくわかります。APIは外部から予期せぬ形式でデータが返ってくることもあり、そのまま扱うとプロパティ名の誤りや値の型の不一致に気づけないまま実行時にエラーが起こってしまいます。そこで、APIレスポンスの構造をインターフェースで明確にしておくことで、TypeScriptの静的型チェックを最大限に活かし、ソースコード全体の信頼性を高めることができます。特に、ユーザーデータや商品データ、各種APIのレスポンスは入れ子構造になっていることが多く、複数のインターフェースを組み合わせて型定義することで大規模なデータ構造も扱いやすくなります。 また、TypeScriptではオプショナルプロパティを活用することで、APIによって返ってくる値が毎回同じとは限らないような場面にも柔軟に対応できます。さらに、配列を含むレスポンスの定義や、関数の戻り値にジェネリック形式で型を指定するテクニックを適用することで、補完精度が高まり、開発の効率性が大きく向上します。APIレスポンスのデータ型を適切に扱うことは、現代のフロントエンド開発では欠かせないスキルのひとつといえるでしょう。次に示す実践的なサンプルコードでは、複雑なAPIレスポンスをどのように設計し、型安全に処理するかをより明確に示しています。

サンプルプログラム：複数階層のAPIレスポンスを型定義して扱う例

// 住所情報の型定義
interface Address {
    city: string;
    zip: string;
    prefecture: string;
}

// ユーザー情報の型定義
interface User {
    id: number;
    name: string;
    email?: string; // オプショナルプロパティ
    address: Address;
}

// APIレスポンス全体の型定義
interface ApiResponse {
    status: string;
    users: User[];
}

// APIデータ取得関数
async function fetchUserList(): Promise<ApiResponse> {
    const response = await fetch("https://example.com/api/users");
    const data: ApiResponse = await response.json();
    return data;
}

// 取得したAPIレスポンスを使う処理
fetchUserList().then(res => {
    console.log("ステータス:", res.status);

    res.users.forEach(user => {
        console.log("名前:", user.name);
        console.log("市区町村:", user.address.city);
        console.log("郵便番号:", user.address.zip);
    });
});

このサンプルでは、APIレスポンスの構造を複数のインターフェースに分割し、それぞれの関連性を明確に保ちながら型定義しています。インターフェースを分けることで、住所情報やユーザー情報の再利用性が高まり、別のAPIレスポンスにも流用できるという利点が生まれます。また、ジェネリック型を返す非同期関数の構造に合わせて、レスポンスの整合性が保たれるように記述されており、大規模なアプリケーションでも管理しやすい柔軟な設計が可能になります。インターフェースを理解し活用することで、複雑で予測しづらいAPIレスポンスであっても安定して取り扱うことができ、型安全な環境でアプリケーションを構築できます。