TypeScriptでAPI通信（Axios/Fetch）！クエリパラメータ・ヘッダーに型を付ける方法を初心者向けに徹底解説

1. API通信と型設定の基本知識

1. API通信と型設定の基本知識

私たちが普段、スマートフォンやパソコンでウェブサイトを見るとき、背景ではインターネットを通じてデータのやり取りが行われています。このデータのやり取りを行う仕組みのことをAPI通信と呼びます。APIとは、特定のプログラムが持つ機能を、外部の別のプログラムから呼び出して利用するための窓口のようなものです。

TypeScriptというプログラミング言語の最大の特徴は、データに型という名前のルールを設定できる点にあります。型とは、そのデータが数字なのか、文字なのか、あるいは白黒の判定なのかをあらかじめ厳しく決めておく約束事です。プログラミングを行う上で、この型を正しく指定しておくことにより、文字を入れるべき場所に間違えて数字を入力してしまうといった、初歩的な失敗を完全に防ぐことができます。

API通信を行う際にも、この型設定は非常に重要な役割を果たします。通信先の窓口に対して、どのような形式のデータを要求するのか、またどのような形式の返答が戻ってくるのかを明確に定義しておくことで、プログラムの動きがとても安定します。パソコンを触ったことがない方でも、型はデータの書類に貼る正しいラベルのようなものだとイメージすると、分かりやすいでしょう。

2. クエリパラメータとヘッダーの役割

2. クエリパラメータとヘッダーの役割

API通信を行うときには、ただ通信のボタンを押すだけではなく、いくつかの細かい情報を一緒に送信する必要があります。その代表的なものがクエリパラメータとヘッダーです。

まず、クエリパラメータについて説明します。これは、通信先のウェブサイトのアドレスの末尾に付け加える、絞り込み条件のようなものです。例えば、インターネットの検索画面で特定の言葉を入力したときに、アドレスの最後に記号や文字が自動的に付け足されているのを見たことがあるかもしれません。このように、データを検索したり、特定の順番に並び替えたりするときに指定する条件のことをクエリパラメータと呼びます。

次に、ヘッダーについて説明します。ヘッダーは、通信を行う際の自己紹介カードや、取扱説明書のような役割を持っています。例えば、私はこういう種類の端末から通信していますという情報や、データの内容は日本語のテキストですという情報、さらには会員専用ページに入るための暗証番号のような情報を、通信の封筒の表書きとして添えるものがヘッダーです。

3. データの組み合わせを表現するインターフェース

3. データの組み合わせを表現するインターフェース

TypeScriptでクエリパラメータやヘッダーに型を付けるためには、まずデータの構造を設計する設計図を作らなければなりません。この設計図を作るための機能をインターフェースと呼びます。インターフェースを使うと、複数のデータを一つにまとめた、オリジナルの型を作成することができます。

例えば、本を検索するためのクエリパラメータの型を作りたい場合、本のタイトルを表す文字データや、発行された年を表す数字データを一つのグループとしてまとめます。このように定義しておくことで、検索を行うプログラムに対して、必ずこの形式に沿ったデータを準備してくださいという命令を出すことができます。これにより、開発中の入力ミスを画面上で即座に見つけることができるようになります。

それでは、実際にクエリパラメータの型を定義するシンプルなプログラムの例を見てみましょう。このコードでは、検索キーワードと、一度に表示するページ数を制限するための型を作成しています。

interface SearchConditions {
    keyword: string;
    limit: number;
}

let currentSearch: SearchConditions = {
    keyword: "プログラミング",
    limit: 10
};

console.log(currentSearch.keyword);

上記のプログラムを実行すると、正しく設定されたキーワードが画面に出力されます。実行結果は次のようになります。

プログラミング

4. 標準機能のフェッチでクエリパラメータに型を付ける

4. 標準機能のフェッチでクエリパラメータに型を付ける

ここからは、実際にAPI通信を行う具体的な方法について学習していきましょう。まずは、パソコンのブラウザに最初から備わっている標準的な通信機能であるフェッチを使用した方法です。フェッチは、特別な準備をしなくてもすぐに使える便利な機能です。

フェッチを使ってクエリパラメータを送信する場合、アドレスの文字列を組み立てる必要があります。その際、型で守られたデータを使用することで、安全にアドレスを作成できます。TypeScriptでは、アドレスの組み立てを行う専用の仕組みを使うことで、型に合わないデータが紛れ込むのを防ぐことができます。

以下のプログラムは、先ほど作成した型を利用して、フェッチ通信を行う際のアドレスにクエリパラメータを安全に組み込む例です。文字の型と数字の型が正しく守られていることを確認しながら処理が進みます。

interface UserFilter {
    status: string;
    page: number;
}

function fetchUserInfo(filter: UserFilter) {
    let url = "https://api.example.com/users?status=" + filter.status + "&page=" + filter.page;
    console.log("通信先のアドレスは、" + url + " です。");
}

let setting: UserFilter = {
    status: "active",
    page: 2
};

fetchUserInfo(setting);

このプログラムを動かすと、型に当てはめられたデータが自動的にアドレスと結合され、通信の準備が整います。実行結果は次のようになります。

通信先のアドレスは、https://api.example.com/users?status=active&page=2 です。

5. 標準機能のフェッチでヘッダーに型を付ける

5. 標準機能のフェッチでヘッダーに型を付ける

続いて、標準機能であるフェッチを使って、通信の自己紹介カードであるヘッダーに型を付ける方法を解説します。ヘッダーには、送信するデータの種類や、認証のための秘密の合言葉を載せることが多いです。

ヘッダーの型を定義するときは、あらかじめ決められた名前の項目に対して、正しい形式の値を指定するように設計します。たとえば、データの種類を指定する項目には必ず決まった文字を入れる、といったルールを作ります。これにより、ヘッダーの名前を書き間違えて通信が失敗するという、よくあるトラブルを未然に防ぐことが可能になります。

次のプログラムは、フェッチ通信のヘッダーに設定するための型を定義し、それを実際に適用する流れを示したものです。安全な通信を行うための設定カードを作成するイメージです。

interface SecurityHeader {
    contentType: string;
    secretToken: string;
}

function sendSecureData(headerData: SecurityHeader) {
    let requestOptions = {
        method: "GET",
        headers: {
            "Content-Type": headerData.contentType,
            "Authorization": headerData.secretToken
        }
    };
    console.log("ヘッダーの設定が完了しました。データの種類は " + requestOptions.headers["Content-Type"] + " です。");
}

let MyHeader: SecurityHeader = {
    contentType: "application/json",
    secretToken: "my-secret-key-123"
};

sendSecureData(MyHeader);

このプログラムを実行すると、設定したヘッダーの情報が正しく読み込まれ、通信の準備が行われたことを示すメッセージが表示されます。実行結果は次のようになります。

ヘッダーの設定が完了しました。データの種類は application/json です。

6. 外部ライブラリのアクシオスとは何か

6. 外部ライブラリのアクシオスとは何か

API通信を行う方法は、ブラウザの標準機能であるフェッチだけではありません。世界中で非常によく使われている、アクシオスという外部の拡張機能を利用する方法もあります。専門用語では、このような拡張機能をライブラリと呼びます。

アクシオスを利用する最大のメリットは、フェッチに比べてプログラムの記述が非常に短く、すっきりと読みやすくなる点にあります。また、通信が失敗したときの原因究明がしやすかったり、自動的にデータを使いやすい形に変換してくれたりする便利な機能がたくさん詰まっています。

TypeScriptとアクシオスを組み合わせると、クエリパラメータやヘッダーの型設定がさらに簡単に行えるようになります。アクシオスが最初から持っている型設定の仕組みに、自分で作った型を当てはめるだけで、非常に強固で安全な通信プログラムを組み立てることができます。初心者の方こそ、このアクシオスの仕組みを覚えることで、エラーの少ない綺麗なプログラムが書けるようになります。

7. アクシオスでクエリパラメータに型を付ける実践

7. アクシオスでクエリパラメータに型を付ける実践

それでは、アクシオスを使ってクエリパラメータに型を適用する具体的なプログラムを作成してみましょう。アクシオスでは、通信の設定を行う場所に、パラメータ専用の項目が用意されています。

この項目に対して、自分で作成したインターフェースの型を割り当てることで、指定された通りの項目しか入力できないように制限をかけることができます。アドレスの文字を自分で細かく結合する必要がないため、書き間違いが起こりにくく、安全性が高まります。

以下のコードは、商品のカテゴリと価格の上限を指定して検索を行うための、型付きパラメータの設定例です。アクシオスの仕組みを分かりやすく表現した単純なプログラムとなっています。

interface ProductQuery {
    category: string;
    maxPrice: number;
}

function searchProducts(query: ProductQuery) {
    let axiosConfig = {
        params: query
    };
    console.log("アクシオスで検索を実行します。カテゴリは " + axiosConfig.params.category + " で、上限価格は " + axiosConfig.params.maxPrice + " 円です。");
}

let condition: ProductQuery = {
    category: "家電",
    maxPrice: 50000
};

searchProducts(condition);

このプログラムを実行すると、アクシオスの設定項目に正しい型でデータが組み込まれ、検索の条件が整ったことが分かります。実行結果は次のようになります。

アクシオスで検索を実行します。カテゴリは 家電 で、上限価格は 50000 円です。

8. アクシオスでヘッダーに型を付ける実践

8. アクシオスでヘッダーに型を付ける実践

最後に、アクシオスを使ってヘッダー情報に型を設定する方法について詳しく見ていきましょう。アクシオスでも、フェッチと同様にヘッダー専用の設定項目が用意されています。

ヘッダーに型を付けることで、システムが受け付けることのできない不正な認証情報や、間違った形式の指定を完全に遮断することができます。特に個人情報を扱う通信や、パスワードが必要な通信においては、このヘッダーの型設定がセキュリティを守るための重要な防壁となります。

以下のプログラムは、通信を受け取るサーバーに対して、操作を行っている人の言語設定と、通信の許可証をヘッダーとして渡すための型設定の例です。これで、クエリパラメータとヘッダーの両方に型を付ける方法がすべて網羅されました。

interface CustomHeaders {
    acceptLanguage: string;
    adminKey: string;
}

function requestAdminPanel(headerSetting: CustomHeaders) {
    let axiosRequest = {
        headers: {
            "Accept-Language": headerSetting.acceptLanguage,
            "X-Admin-Key": headerSetting.adminKey
        }
    };
    console.log("管理画面への通信ヘッダーを設定しました。言語は " + axiosRequest.headers["Accept-Language"] + " です。");
}

let finalHeader: CustomHeaders = {
    acceptLanguage: "ja",
    adminKey: "admin-pass-999"
};

requestAdminPanel(finalHeader);

プログラムを実行すると、安全なヘッダーが作成され、通信の準備が完全に完了したことを確認できます。実行結果は次のようになります。

管理画面への通信ヘッダーを設定しました。言語は ja です。