LilyTech

RESTful APIとは?注文アプリで学ぶリクエストとレスポンス

Nguyễn Chính Ngọc Liên監修Hoàng Linhコンテンツ管理Lê Mạnh

RESTful APIとは?実際のリクエストとレスポンスの例を、オンライン注文の仕組みを通して解説します。

注文アプリで料理の一覧を表示し、注文を送信して、配達状況を更新するには、バックエンドのソフトウェア同士がデータをやり取りする必要があります。RESTful APIは、そのやり取りを設計する方法の一つです。明確なルールに基づいて、アプリからサーバーにリクエストを送り、データを受け取れるようにします。

この記事では、LilyTechがRESTful APIとは何か、エンドポイントの構造の読み方、オンライン注文を例にした代表的なHTTPメソッドについて解説します。リクエストとレスポンスのJSON例を通じて、実際のアプリでAPIがどのように動作するかをイメージできます。

RESTful APIとは?

APIはApplication Programming Interfaceの略で、日本語ではアプリケーション・プログラミング・インターフェースといいます。あるソフトウェアが、別のソフトウェアに機能やデータを要求する方法を定めたものです。たとえば、スマートフォンのアプリはAPIを呼び出してサーバーからメニューを取得できます。内部でデータがどのように保存されているかを知る必要はありません。

RESTful APIと、アプリがサーバーに接続する仕組みについて話し合う開発者
RESTful APIは、リソース、エンドポイント、リクエストを通じてアプリとサーバーがデータをやり取りするためのルールを定めます。

RESTはRepresentational State Transferの略で、Webサービスを設計するためのアーキテクチャスタイルです。RESTの原則に沿って適切に構築されたAPIを、RESTful APIと呼びます。実際には、HTTPを介してリソースをやり取りし、多くの場合JSONを送受信するWeb APIを指す言葉として使われています。

このモデルでは、料理、顧客、注文などのデータをリソースとして表現します。それぞれのリソースには通常、エンドポイントと呼ばれる固有のアドレスがあります。アプリはHTTPメソッドを使ってエンドポイントにリクエストを送信し、サーバーはそのリクエストを処理して、通常はステータスコードと必要なデータを含むレスポンスを返します。

RESTful APIは、プログラミング言語でも特定の製品でもありません。システム間の通信を整理する方法です。一貫したルールに基づいて、開発チームはWebサイトやモバイルアプリを構築したり、ソフトウェア同士を連携させたりしやすくなります。

エンドポイントの構造とAPIリクエスト

https://api.bepnhanh.vnをAPIのベースURLとする注文サービスをイメージしてください。リクエストは通常、HTTPメソッド、エンドポイント、ヘッダーで構成され、必要に応じてボディも含みます。エンドポイントは、アプリが操作したいリソースや処理を指定します。

たとえば、/api/v1/menu-itemsは料理の一覧を表すエンドポイントです。/apiはAPIのパスであること、v1はバージョン、menu-itemsはリソースの種類を示します。別の例である/api/v1/orders/5821は、注文番号5821を操作するためのエンドポイントです。

料理の一覧を取得するリクエストは、次のように記述できます。

メソッドとエンドポイント: GET https://api.bepnhanh.vn/api/v1/menu-items?category=drink

ヘッダー: Accept: application/json

?category=drinkはクエリパラメーターで、カテゴリによる料理の絞り込みに使います。ヘッダーには、アプリが受け入れるデータ形式や認証情報など、リクエストに関する追加情報を指定します。注文を作成する操作では、JSONデータを含むボディも通常追加されます。

エンドポイントの命名を明確にすると、APIの可読性と拡張性が高まります。一般に、リソース名には/ordersや/customersのような名詞を使い、操作はHTTPメソッドで表します。このルールにより、操作ごとに個別のパスを大量に作る必要がなくなります。

よく使われるHTTPメソッドを例で解説

HTTPメソッドは、リソースに対してアプリが何を行いたいのかをサーバーに伝えます。RESTful APIでよく使われるメソッドはGET、POST、PUT、PATCH、DELETEです。注文の例では、次のように使い分けられます。

注文処理の流れを例に、RESTful APIのHTTPメソッドを分析するエンジニアチーム
GET、POST、PUT、PATCH、DELETEなどのHTTPメソッドによって、RESTful APIでリソースに対する操作を表現できます。
  • GET — データの取得: GET /api/v1/menu-itemsで料理の一覧を取得したり、GET /api/v1/orders/5821で特定の注文を確認したりします。GETでは通常、リソースの作成や更新を目的としたデータは送信しません。
  • POST — リソースの作成: 料理や配達先の情報を添えてPOST /api/v1/ordersを送信し、新しい注文を作成します。処理が成功すると、サーバーは作成された注文番号を返す場合があります。
  • PUT — リソースの置き換え: 更新に必要な情報をすべて含めてPUT /api/v1/orders/5821を送信します。PUTは通常、リソース全体の置き換えを意味するため、APIの仕様に応じて必要な項目をすべて送る必要があります。
  • PATCH — リソースの部分更新: 注文全体を再送信する代わりに、PATCH /api/v1/orders/5821を送信して、ステータスや配達先だけを変更します。
  • DELETE — リソースの削除: DELETE /api/v1/orders/5821を送信し、システムのポリシーに応じて注文の削除またはキャンセルを要求します。

各操作の具体的な意味は、APIのドキュメントによって異なります。たとえば、支払い済みの注文は削除できず、「キャンセル済み」にステータスを変更するだけのシステムもあります。そのため、アプリ側はサーバーが公開している業務ルールに従う必要があります。

実際のJSONリクエストとレスポンスの例

顧客がコーヒーを2杯注文し、選択済みの住所への配達を指定したとします。アプリは注文作成用のエンドポイントにPOSTリクエストを送信します。ボディには、料理ID、数量、配達情報などを次のように含めます。

注文アプリでRESTful APIのJSONリクエストとレスポンスを確認するエンジニア
JSONのリクエストとレスポンスの例です。APIが注文情報を受け取り、処理した後、注文番号とステータスを返します。

リクエスト: POST /api/v1/orders

ヘッダー: Content-Type: application/json; Authorization: Bearer <access_token>

ボディ: {"items": [{"menu_item_id": 42, "quantity": 2}], "delivery_address_id": 918, "note": "氷少なめ"}

Content-Typeヘッダーは、ボディがJSON形式で送信されることを示します。Authorizationヘッダーには、誰が注文しているかをサーバーが確認するための認証情報が含まれます。実際のシステムでは、アクセストークンを安全に管理し、暗号化された接続で送信する必要があります。機密情報をURLに含めてはいけません。

注文の作成が成功した場合、サーバーは次のようなレスポンスを返します。

レスポンス: HTTP 201 Created

ボディ: {"id": 5821, "status": "pending_confirmation", "total": 98000, "currency": "VND", "created_at": "2025-03-08T10:15:00Z"}

201 Createdは、新しいリソースが作成されたことを示すステータスコードです。返されるデータには、注文番号、ステータス、合計金額、作成日時が含まれます。アプリは注文番号5821を使って、注文状況の確認画面へ移動できます。

アプリがGET /api/v1/orders/5821を呼び出すと、サーバーは注文データとともにHTTP 200 OKを返す場合があります。statusの値は処理の進行に応じて変わり、pending_confirmationからpreparing、さらにdeliveringへと移行することがあります。注文番号が存在しない場合は404 Not Found、ログインしていない場合やトークンが無効な場合は401 Unauthorizedが返されることがあります。

ステータスコードを使うと、JSONの内容から推測することなく、リクエストが成功したかエラーになったかをアプリが判断できます。よく使われるコードには、処理の成功を示す200、送信データが無効であることを示す400、権限不足を示す403、リソースが見つからないことを示す404、サーバーエラーを示す500があります。

RESTful APIの設計・連携時の注意点

上記の例では、分かりやすさを優先して一部の詳細を簡略化しています。APIを実際の製品に導入する際は、企業と開発チームがデータ形式、エラー処理、セキュリティに関するルールを早い段階で統一することが重要です。これらの判断は、システムの連携や保守のしやすさに直接影響します。

  • エンドポイントの設計に一貫性を持たせる: 分かりやすいリソース名を使い、必要に応じてバージョンを分け、データ項目の命名方法を統一します。
  • 役立つエラー情報を返す: 適切なステータスコードと、開発者が対処できる明確なメッセージを返します。ただし、機密性の高い内部情報を公開しないようにします。
  • データを保護する: HTTPSを使用し、ユーザー認証や役割に応じた権限管理を行い、処理前に入力データを検証します。
  • パフォーマンスを管理する: 大量の一覧にはページネーション、フィルタリング、結果件数の上限を設けます。過負荷のリスクを抑えるため、APIの呼び出し頻度の制限も検討します。
  • ドキュメントを作成してテストする: エンドポイント、メソッド、パラメーター、レスポンス、想定されるエラーを記載し、開発チームが正確に連携できるようにします。

RESTful APIは、Webサイト、モバイルアプリ、管理システム、パートナー企業のサービスなどを連携させる場合に適しています。ただし、アーキテクチャの選択は、データ、パフォーマンス、セキュリティ、運用体制に関する要件によって異なります。優れたAPI設計とは、URLを適切に設定するだけでなく、企業の業務プロセスを正しく反映することです。

まとめ:RESTful APIを理解してシステム連携を効率化

RESTful APIは、リソース、エンドポイント、HTTPメソッドを通じてアプリケーション間の通信を整理する方法です。GETでデータを取得し、POSTで注文を作成し、PUTやPATCHで更新し、DELETEでリソースを削除する仕組みが分かると、デジタル製品におけるリクエストとレスポンスの流れを理解しやすくなります。JSON形式とステータスコードを使うことで、一定のルールに従ったデータ交換が可能になり、開発や連携もスムーズになります。

企業でWebサイトやモバイルアプリを開発する場合や、APIをERPなどの既存システムと連携させる場合は、LilyTechが業務プロセスに合ったソリューションをご提案します。要件や効果的な導入方針について、ぜひLilyTechまでお問い合わせください。

著者について

Nguyễn Chính Ngọc Liên

Nguyễn Chính Ngọc Liên tốt nghiệp Đại học Công nghiệp và có 7 năm kinh nghiệm trong lĩnh vực viết nội dung SEO. Với nền tảng kiến thức chuyên môn cùng kinh nghiệm thực tế, Ngọc Liên tập trung xây dựng những nội dung rõ ràng, hữu ích, chuẩn SEO và đáp ứng nhu cầu tìm kiếm của người đọc.