はじめに

Webアプリケーション開発において、APIはフロントエンドとバックエンドをつなぐ重要な役割を担っています。

しかし、はじめてAPIを実装する方にとっては、とても難しく感じるかもしれません。そもそもAPIとは何か？そのイメージを掴むことさえ難しいこともあるでしょう。

APIを理解しようと「API 入門」などで検索すると、多くのサイトで次のような説明が目に入るかもしれません。

この説明自体は正しく、特にAPIの概要をざっくり理解したい営業職や企画職の方には非常に役立つでしょう。しかし、これからAPIを初めて作ろうとするエンジニアにとっては、かえって混乱を招く可能性があります。

こうした疑問が次々と浮かび、何から手をつければ良いか分からなくなることもあるでしょう。

APIを実装できるようになる過程には、一種のパラドックスがあります。それは、APIを理解するためには実際に手を動かして実装してみる必要がある一方で、実装するためにはAPIを理解していなければならないというものです。

そこで本記事では、APIの理解と実際のAPIの実装という２つの側面のうち、まずはAPIの本質をよりシンプルに捉え、エンジニアとしてAPIを作るはじめの一歩をわかりやすく解説していきます。

今回は、APIを実装するために最低限必要な知識をまとめました。最後に、APIを実装するためのおすすめのフレームワークであるNestJSについて簡単にご紹介します。

続編である「NestJSでAPIを書いてみよう！［はじめてのAPI実装 第２回］」では、実際にNestJSを使ってAPIを実装してみます。

なお、この記事では厳密な説明よりも「初めてAPIを作る人が具体的なイメージを持つこと」を優先しています。細かい部分は理解できなくても、まずは全体の流れを掴んでいただければ大丈夫です。

この記事を読むことで得られること

• APIの具体的なイメージを持てる
• NestJSの基本構造を把握できる
• シンプルなAPIを実装できる
• 実装したAPIをテストできる

想定読者

• APIを初めて作る人
• JavaScript・TypeScriptの基本を押さえている人
• Node.jsやExpressに触れたことがある人（必須ではない）
• 簡単なプロジェクトを通じてAPIの基礎を身につけたい人

APIとは？APIのイメージを掴もう！

API（エーピーアイ）とは、「Application Programming Interface」の略で、アプリケーション同士がやり取りをするための窓口のようなものです。

これをもう少し簡単に言うと、URLを叩いたら何らかのデータが返ってくる仕組みのことだと考えるとイメージしやすいです。

ウェブページとAPIの関係

この記事を読んでいただいている方は、普段からGoogle ChromeやMicrosoft Edgeなどのブラウザを使い、様々なウェブサイトを見て楽しんでいることでしょう。

ブラウザでウェブサイトを開くとき、URLを入力しますよね？

例えば、架空のウェブサイト「ヒプノクラブ」があったとします。

ヒプノクラブのURLが「https://hipnoclub.com」だったとしましょう。

ブラウザに「https://hipnoclub.com」を入力し、そのウェブページを開くと、サーバーからウェブページの情報（HTMLや画像など）が送られてきて、画面に表示されます。

このとき、ブラウザはサーバーに「ウェブページの情報をください」というリクエスト（要求）を送っています。リクエストとは、サーバーに対して「何かをしてください」と要求を出す動作を指します。

APIもこれと似ています。

ただ、ウェブページとは違い、画面を表示する情報（HTML）ではなく、データそのものを返してくれるのがAPIです。

例えば、ヒプノクラブAPIに「https://hipnoclub.com/members」というURLでリクエストを送ると、サーバーはそのヒプノクラブに登録されているメンバー一覧をデータとして返します。

そのデータはこんな感じかもしれません。

[
  {
    "id": 1,
    "name": "Tanaka"
  },
  {
    "id": 2,
    "name": "Sato"
  },
 {
    "id": 3,
    "name": "Suzuki"
  }
]

APIはウェブページと同じようにURLを使いますが、返ってくるのは画面を表示するためのHTMLではなく、データそのものです。このように、APIはプログラムが情報をやり取りするための仕組みとして、ウェブページとは異なる役割を持っています。

APIは「アプリケーション同士の会話」

APIをもっとイメージしやすくするために、このように考えてみてください

• APIはアプリケーション同士の会話のルール
• 「このURLを使えば、こういうデータを返すよ」というルールをプログラムで作る
• そのルールに従ってプログラムを書けば、データのやり取りができる

APIを理解するために最低限覚えておくべき3つのこと

リクエスト

• 「URLを叩く」ことでサーバーに情報を要求します。
• 例えば、「https://hipnoclub.com/members」というURLにリクエストを送ると、メンバー一覧を要求していることになります。

レスポンス

• サーバーはリクエストを受け取り、指定された情報を返します。
• 例えば、メンバー一覧のリクエストに対して、名前やIDのリストを返します。

データの形式

• APIが返すデータは、通常「JSON（ジェイソン）」という形式です。
• JSONは、データをキーと値のペアで表現するフォーマットです。

ウェブページとAPIの違い

ウェブページ	API
HTMLを返して画面を表示する	データ（JSONなど）を返すだけ
人間が直接ブラウザで見るためのもの	プログラムがデータをやり取りするためのもの
例： https://hipnoclub.com	例： https://hipnoclub.com/members

要するに、APIって何？

• APIはURLを叩いたらデータが返ってくる仕組み
• ブラウザでウェブページを開くのと似ているけれど、返ってくるのはデータそのもの
• 開発者にとってはデータをやり取りする窓口

まずはこのイメージを持って、次に進んでみましょう！

もう少しだけAPIへの理解を深める

前章では、APIを使って情報を取得する仕組みについて説明しました。URLを叩くとデータが返ってくるというシンプルなイメージを持っていただけたかと思います。

しかし、APIの役割は「情報を取得する」だけではありません。APIは、情報を登録したり、更新したり、削除したりすることもできるのです。これらをまとめて「CRUD（クラッド）」操作と呼びます。

CRUDって何？

CRUDとは、APIが提供する4つの基本的な操作の頭文字を取ったものです。

• Create（登録）：新しい情報を登録する操作
• Read（取得）：既存の情報を取得する操作（前の章で説明した部分）
• Update（更新）：既存の情報を変更する操作
• Delete（削除）：不要になった情報を削除する操作

次に、これらの操作を具体的に見ていきましょう。

Create（登録）

新しい情報を登録する操作です。例えば、ヒプノクラブのメンバー情報を登録する場合を考えてみましょう。

リクエストの例

「https://hipnoclub.com/members」というURLに新しいメンバー情報の登録リクエストを送ると、そのデータがサーバーに登録されます。

登録するデータ（リクエストの中身）はこんな感じです。

{
  "name": "Yamada",
  "age": 25,
  "email": "yamada@example.com"
}

これをAPIに送ると、新しいメンバー「Yamada」がデータベースに追加されます。

Read（取得）

これは前の章で説明した部分です。既存のメンバー情報を取得する操作です。

リクエストの例

「https://hipnoclub.com/members」に取得リクエストを送ると、登録されているメンバーの一覧が返されます。

[
  {
    "id": 1,
    "name": "Tanaka",
    "age": 30,
    "email": "tanaka@example.com"
  },
  {
    "id": 2,
    "name": "Sato",
    "age": 28,
    "email": "sato@example.com"
  }
]

Update（更新）

既存の情報を変更する操作です。例えば、IDが1のTanakaさんの名前を「Tanaka Taro」に変更する場合を考えます。

リクエストの例

「https://hipnoclub.com/members/」にIDの1を加えて、「https://hipnoclub.com/members/1」というURLに、以下のようなデータの更新リクエストを送ると、サーバーは「IDが1のメンバー」を見つけ、その情報を更新します。

{
  "name": "Tanaka Taro",
  "age": 30,
  "email": "tanaka@example.com"
}

Delete（削除）

不要になった情報を削除する操作です。例えば、IDが2のSatoさんを削除する場合を考えます。

リクエストの例

「https://hipnoclub.com/members/」にIDの2を加えて、「https://hipnoclub.com/members/2」というURLに削除リクエストを送ると、IDが2のメンバー「Sato」が削除されます。

CRUDのまとめ

• Create：　新しい情報を登録する
• Read：　既存の情報を取得する
• Update：　情報を変更する
• Delete：　情報を削除する

これらは、APIが提供する基本的な機能です。

HTTTPメソッドを理解しよう！

前章では、「登録リクエスト」、「取得リクエスト」、「更新リクエスト」、「削除リクエスト」という言葉を使い、APIが情報の登録、取得、更新、削除を行う仕組みを説明しました。しかし、具体的にどのようにしてこれらの操作をAPIに伝えるのか、疑問に思ったかもしれません。

実は、リクエストには「HTTPメソッド」と呼ばれる種類があり、これらを使い分けることでサーバーに対して「何をしたいのか」を伝えています。今回は、このHTTPメソッドであるGET、POST、PUT、DELETEについて、分かりやすく解説していきます。

これを理解することで、APIの基礎をしっかり押さえることができます。

HTTPメソッドとは？

まず、HTTPメソッドとは、クライアント（あなたのパソコンやスマートフォン）がサーバーに対して「何をしたいのか」を伝えるための「動詞」のようなものです。基本的なものは次の４つです。

• GET：　情報の取得（Read）
• POST：　新しい情報の作成（Create）
• PUT：　既存の情報の更新（Update）
• DELETE：　情報の削除（Delete）

これらのメソッドを使い分けることで、サーバーはクライアントからのリクエストが「何がしたいのか」を理解し、適切な処理を行います。

GETメソッド：情報の取得

前章で説明した「メンバー一覧を取得する」場合、GETメソッドを使用します。
データの取得専用リクエストです。

リクエストの例

GET https://hipnoclub.com/members

このリクエストを送ると、サーバーは登録されているメンバーの一覧を返してくれます。

レスポンスの例

[
  {
    "id": 1,
    "name": "Tanaka",
    "age": 30,
    "email": "tanaka@example.com"
  },
  {
    "id": 2,
    "name": "Sato",
    "age": 28,
    "email": "sato@example.com"
  }
]

POSTメソッド：新しい情報の作成

新しいメンバー「Yamada」を登録する場合、POSTメソッドを使用します。
新しいリソースを作成するリクエストです。

リクエストの例

POST https://hipnoclub.com/members

リクエストボディ（送信するデータ）

{
  "name": "Yamada",
  "age": 25,
  "email": "yamada@example.com"
}

サーバーはこのデータを受け取り、新しいメンバーとして登録します。

レスポンスの例

{
  "id": 3,
  "name": "Yamada",
    "age": 25,
  "email": "yamada@example.com"
}

登録した情報をレスポンスしています。

PUTメソッド：既存の情報を更新

IDが１の「Tanaka」さんの名前を「Tanaka Taro」に更新する場合、PUTメソッドを使用します。
既存のリソースを置き換えるためのリクエストです。

リクエストの例

PUT https://hipnoclub.com/members/1

リクエストボディ

{
  "name": "Tanaka Taro",
  "age": 30,
  "email": "tanaka@example.com"
}

サーバーはIDが１のメンバー情報を新しいデータで更新します。

レスポンスの例

{
  "id": 1,
  "name": "Tanaka Taro",
  "age": 30,
  "email": "tanaka@example.com"
}

更新した情報をレスポンスしています。

DELETEメソッド：情報の削除

IDが２の「Sato」さんを削除する場合、DELETEメソッドを使用します。
指定したリソースを削除するリクエストです。

リクエストの例

DELETE https://hipnoclub.com/members/2

サーバーはIDが２のメンバー情報を削除します。

レスポンスの例

{
  "message": "ID 2のメンバーを削除しました。"
}

削除したメンバーをレスポンスしています。

HTTPメソッドとCRUDの対応関係

CRUD操作	HTTPメソッド	用途
Create	POST	新しいリソースの作成
Read	GET	リソースの取得
Update	PUT	リソースの更新
Delete	DELETE	リソースの削除

このように、CRUD操作とHTTPメソッドは対応しています。APIを設計・利用する際は、この対応関係を意識することで、サーバーとクライアントの間で適切な通信が行えます。

はじめてのAPI実装におすすめ！NestJSを知ろう

これまで、APIの基本的なイメージについて解説してきました。「なんとなく理解できたけれど、まだ完全には腑に落ちない」という感覚を持つ方もいるかもしれません。実はそれで大丈夫です！この記事の「はじめに」でも述べたように、APIを本当に理解するためには、実際に手を動かして実装してみることが重要です。

そこで、この記事の締めくくりとして、APIを実装する際におすすめのフレームワークであるNestJSを簡単にご紹介します。

NestJSとは

NestJSは、WebアプリケーションやAPIを作るためのモダンなバックエンドフレームワークです。Node.js上に構築されており、TypeScriptというプログラミング言語を使用して開発が行われます。そのため、TypeScriptの特徴を活かした開発が可能です。

NestJSとTypeScript

NestJSの最大の特徴の1つは、フレームワーク自体がTypeScriptで開発されていることです。

TypeScriptを使うことで、APIのリクエストやレスポンスの型を明確に定義できるため、開発中のミスを未然に防ぐことができます。例えば、サーバーが返すユーザー情報が「文字列」として定義されているのに、クライアント側で「数値」として扱おうとした場合、TypeScriptがエラーとして検知してくれるため、問題を早期に解決できます。

これにより、コードの安全性や可読性が向上し、効率的な開発が可能になります。

フロントエンドとバックエンドを同じ言語で扱える

もう1つの大きなメリットは、フロントエンドとバックエンドを同じ言語（TypeScript）で開発できる点です。フロントエンドもバックエンドもTypeScriptで書けるので、新しい言語を覚える必要がなく、学習コストを削減できます。

さらに、フロントエンドとバックエンドでデータ型を共有できるため、開発がスムーズになります。例えば、バックエンドで定義した「ユーザー情報」の型をフロントエンドでも使うことで、データの整合性を保ち、開発ミスを防げます。

明確なアーキテクチャ

NestJSは、モジュールやコントローラー、サービスといった明確なアーキテクチャを持っています。これにより、どこに何を書けば良いかが分かるようになっています。

例えば、次のような流れでAPIを作成します。

• コントローラー: リクエストを受け取る部分
• サービス: ビジネスロジックを記述する部分
• モジュール: コントローラーやサービスを1つの機能としてまとめる部分

これらの役割が明確になっているため、効率的に開発を進めることができます。

まとめ

ここまで、APIの基本的な概念と、それを理解するために最低限必要な知識を解説してきました。APIとは何か、その役割や仕組み、そしてCRUD操作とHTTPメソッドの関係について、少しずつイメージが掴めてきたのではないでしょうか。

また、最後に紹介したNestJSは、これからAPIを実装する際に非常に役立つフレームワークです。TypeScriptを活用した型安全な開発や、明確なアーキテクチャにより、効率的に高品質なAPIを構築できます。

続編である「NestJSでAPIを書いてみよう！［はじめてのAPI実装 第２回］」では、いよいよこのNestJSを使って実際にAPIを作っていきます！

初学者でも無理なく進められる手順で、シンプルなCRUD機能を備えたAPIを完成させる方法を解説します。ぜひお楽しみに！