REST APIのリソース設計（エンドポイント設計）を初心者向けにわかりやすく解説！

REST APIのリソース設計（エンドポイント設計）

新人と先輩の会話形式で理解しよう

新人

「REST APIってよく聞きますけど、そもそも何なんですか？」

先輩

「REST APIは、Webアプリケーションでよく使われる仕組みで、HTTPを使ってデータのやりとりをするんだ。」

新人

「データのやりとりって、どういうふうにするんですか？」

先輩

「それを理解するには、リソースやエンドポイントの設計について知っておくと良いよ。順番に説明していこう。」

1. REST APIとは何か？

REST APIとは、「Representational State Transfer（表現状態の転送）」という設計スタイルに基づいたAPI（アプリケーションプログラミングインターフェース）のことです。Webシステムにおいて、クライアントとサーバーがHTTPを使ってデータをやり取りするためのルールや方法を定めています。

例えば、フロントエンドから「商品一覧を取得したい」というリクエストがあった場合、サーバーはそのリクエストに応じて商品データをJSON形式などで返します。これがREST APIの基本的な考え方です。

REST APIは「HTTPのGET、POST、PUT、DELETEといったメソッド」と「リソースを表すエンドポイントURL」を組み合わせて設計されます。これにより、シンプルでわかりやすく、拡張性の高いAPI設計が可能になります。

2. リソースとは何か？なぜリソース設計が重要なのか？

REST APIにおける「リソース」とは、対象となるデータそのものを意味します。例えば、「ユーザー情報」や「商品情報」、「注文履歴」などがリソースの一例です。

このリソースを正しく設計することで、API全体の使いやすさやメンテナンス性が大きく向上します。具体的には、リソースを「名詞」で表し、それに対応する操作をHTTPメソッドで表すようにします。

例えば、ユーザー一覧を取得したい場合は、以下のようなURL設計になります。


GET /users

「/users」がリソースで、「GET」が取得操作を意味しています。こうした設計により、誰が見ても直感的に意味が分かるAPIになります。

また、リソース設計は一貫性が大事です。例えば、「/getUser」「/fetchUserInfo」などバラバラな命名にすると、利用者が混乱します。リソース＝名詞のルールを守り、統一されたエンドポイント設計を行いましょう。

3. エンドポイントの基本構造（URL設計の原則）

REST APIのエンドポイントは、リソースを表すURLのことです。基本的な構造は非常にシンプルで、「ドメイン名 + リソースパス」で構成されます。

例えば、商品情報を扱うAPIのエンドポイント設計は次のようになります。


GET /products            // 商品一覧の取得
GET /products/1         // 商品IDが1の情報を取得
POST /products          // 商品の新規登録
PUT /products/1         // 商品IDが1の情報を更新
DELETE /products/1      // 商品IDが1の情報を削除

このように、GET、POST、PUT、DELETEといったHTTPメソッドによって、それぞれの操作を表現します。URL自体は操作を含まず、常にリソース名（名詞）で表すことが重要です。

Springでこうしたエンドポイントを定義する場合は、以下のように@Controllerを使って実装します。


@Controller
@RequestMapping("/products")
public class ProductController {

    @GetMapping
    public String listProducts(Model model) {
        // 商品一覧取得の処理
        return "product/list";
    }

    @GetMapping("/{id}")
    public String getProduct(@PathVariable Long id, Model model) {
        // 商品詳細取得の処理
        return "product/detail";
    }

    @PostMapping
    public String createProduct(@ModelAttribute Product product) {
        // 新規登録処理
        return "redirect:/products";
    }

    @PostMapping("/{id}")
    public String updateProduct(@PathVariable Long id, @ModelAttribute Product product) {
        // 更新処理（本来はPUTが望ましいが、HTMLフォームの制限でPOST使用）
        return "redirect:/products/" + id;
    }

    @PostMapping("/{id}/delete")
    public String deleteProduct(@PathVariable Long id) {
        // 削除処理（DELETEの代わりにPOST）
        return "redirect:/products";
    }
}

Spring MVCではHTMLフォームの制約によりPUTやDELETEが使えないため、POSTで代用するのが一般的です。

また、Pleiades環境では、Gradleでプロジェクトを作成し、依存関係もチェックボックスで追加できます。設定ファイルに直接触れずに環境構築できるため、初心者にも扱いやすいです。

このように、REST APIのリソース設計とエンドポイント設計は、直感的で一貫性のあるAPIを提供するために欠かせない要素です。次回はHTTPメソッドの使い分けや、パラメータ設計について詳しく見ていきましょう。

4. HTTPメソッド（GET、POST、PUT、DELETE）の使い分けと意味

REST APIでは、HTTPメソッドを使って、リソースに対する操作を表現します。ここでは、代表的なメソッドであるGET、POST、PUT、DELETEについて、それぞれの意味と使い分けを解説します。

GETは、データを「取得」するためのメソッドです。URLにパラメータを付けて、サーバーから情報を受け取るだけの安全な操作に使います。

POSTは、新しいデータを「作成」する際に使用します。フォームの送信や新規登録に使うことが多いです。

PUTは、既存のデータを「更新」するための操作です。対象のリソース全体を上書きする意味を持ちます。

DELETEは、指定されたリソースを「削除」するために使います。これらのメソッドは、それぞれに明確な役割があります。

Spring MVCで@Controllerを使って実装する場合、HTTPメソッドに応じたアノテーションを使います。以下はその基本的な書き方です。


@Controller
@RequestMapping("/users")
public class UserController {

    @GetMapping
    public String listUsers(Model model) {
        return "user/list";
    }

    @PostMapping
    public String createUser(@ModelAttribute User user) {
        return "redirect:/users";
    }

    @PutMapping("/{id}")
    public String updateUser(@PathVariable Long id, @ModelAttribute User user) {
        return "redirect:/users/" + id;
    }

    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        return "redirect:/users";
    }
}

ただし、前回も述べた通り、HTMLフォームではPUTやDELETEが直接使えないため、POSTで代用するケースも多く見られます。

5. RESTらしいエンドポイント設計とは？

RESTful設計では、エンドポイントは操作を含めずに「リソース名（名詞）」だけで表すのが基本です。たとえば、「ユーザーの情報を取得する」という操作でも、エンドポイントは以下のように設計します。


GET /users           // 全ユーザーを取得
GET /users/10        // IDが10のユーザーを取得
POST /users          // 新しいユーザーを作成
PUT /users/10        // IDが10のユーザーを更新
DELETE /users/10     // IDが10のユーザーを削除

このように、エンドポイントの命名は「動詞を避け、名詞を使う」のが鉄則です。「/getUser」「/createUser」などのように動詞を含めてしまうと、RESTの原則から外れてしまいます。

また、エンドポイントの階層構造も重要です。例えば、ユーザーに紐づく注文情報を扱う場合、次のようなURL設計が適切です。


GET /users/10/orders       // ユーザーIDが10の注文一覧を取得
GET /users/10/orders/5     // ユーザーIDが10の注文IDが5の詳細取得

このようにリソースの関係性をURLで表現することで、APIの構造がわかりやすくなり、メンテナンス性も高まります。

Springの@Controllerでこのような階層的エンドポイントを実装する場合、複数の@RequestMappingを組み合わせて使用します。


@Controller
@RequestMapping("/users/{userId}/orders")
public class OrderController {

    @GetMapping
    public String listOrders(@PathVariable Long userId, Model model) {
        return "order/list";
    }

    @GetMapping("/{orderId}")
    public String getOrder(@PathVariable Long userId, @PathVariable Long orderId, Model model) {
        return "order/detail";
    }
}

URLに階層構造を持たせることで、リソース同士の関連性が明確になり、APIの設計として非常に自然な形になります。

6. パスパラメータとクエリパラメータの違いと使い分け

REST APIでは、URLの中で値を渡す方法として、「パスパラメータ」と「クエリパラメータ」の2つがあります。それぞれの違いと使い分けを理解することが、パラメータ設計においてとても重要です。

パスパラメータは、URLの一部として指定する値で、特定のリソースを識別するために使われます。以下はその例です。


GET /products/5     // IDが5の商品を取得

この場合、「5」という値は商品IDであり、どの商品かを一意に示す役割を持ちます。

一方で、クエリパラメータは、URLの末尾に「?」を付けて追加する形式で、条件やオプションを指定するために使われます。以下はその例です。


GET /products?category=book&page=2

このように、クエリパラメータは「一覧のフィルタ」「ページ番号」「検索条件」などに使われるのが一般的です。

Springでの実装では、パスパラメータは@PathVariable、クエリパラメータは@RequestParamで受け取ります。具体的なコードは以下の通りです。


@Controller
@RequestMapping("/products")
public class ProductController {

    @GetMapping("/{id}")
    public String getProduct(@PathVariable Long id, Model model) {
        return "product/detail";
    }

    @GetMapping
    public String listProducts(@RequestParam(required = false) String category,
                                @RequestParam(defaultValue = "1") int page,
                                Model model) {
        return "product/list";
    }
}

このように、リソースの一意な識別にはパスパラメータを使い、条件指定やオプションにはクエリパラメータを使うのが、REST APIにおけるベストプラクティスです。

どちらを使うかで迷った場合は、「それがリソースの特定に不可欠かどうか」を基準に判断するとよいでしょう。

7. よくある設計ミスとその回避方法（動詞エンドポイント・複雑なURLなど）

初心者がREST APIのエンドポイント設計でよくやってしまうミスとして、動詞を使ってしまうケースがあります。例えば以下のようなエンドポイントはNGです。


GET /getUser
POST /createOrder
DELETE /deleteProduct

これらは一見わかりやすく見えますが、RESTの原則から外れた設計です。本来のREST APIでは、エンドポイントは「名詞」で表し、操作はHTTPメソッドで表現するのが基本です。

正しくは、以下のように設計します。


GET /users
POST /orders
DELETE /products/1

このようにすることで、誰が見ても直感的に理解できるREST APIになります。

また、複雑すぎるURL構造もよくある落とし穴です。例えば以下のようなURLは避けるべきです。


GET /userManagement/getUserDetailsById/10

これは、リソースと操作が混在しており、どこに何があるのか非常に分かりにくくなっています。こうした場合も、リソースを明確に表し、URLはシンプルかつ階層的に設計しましょう。


GET /users/10

エンドポイントが深すぎたり、意味のない英数字を含んだパスを設けると、利用者が混乱する原因になります。常に読みやすく・予測しやすいURL設計を心がけましょう。

8. リソース設計のベストプラクティス（シンプル・予測可能・一貫性）

REST APIを設計するうえで重要なのは、「予測可能で一貫性のあるリソース設計」を行うことです。以下のようなポイントを押さえると、保守性の高いAPIになります。

① シンプルで直感的な命名

エンドポイントは極力短く、かつ意味が明確なものにしましょう。例えば「/users」はユーザーを、「/orders」は注文情報を示します。省略語や略語を多用すると逆に分かりづらくなるため避けるべきです。

② 複数形を使う

リソースは基本的に「一覧」を扱う可能性があるため、複数形で表現するのが一般的です。たとえば「/user」ではなく「/users」とすることで、複数のデータを返すことが自然に伝わります。

③ 一貫性を守る

API全体で命名規則やパターンに統一性があると、利用者はストレスなく操作できます。たとえば、「/users」「/products」「/orders」といった形で名詞ベースの設計を貫くことが大切です。

④ ステータスコードを正しく使う

エンドポイント設計とは少し離れますが、返すレスポンスのステータスコードもREST APIでは非常に重要です。「200 OK」「201 Created」「404 Not Found」「400 Bad Request」などを適切に使い分けましょう。

このようにリソース設計におけるベストプラクティスを守ることで、他の開発者や利用者にとっても親切で理解しやすいREST APIとなります。

9. Springでリソースエンドポイントを設計するサンプルコード（@Controller使用）

ここでは、Spring MVCを使ってREST APIのエンドポイントをどのように実装するかを、実際のコード例で紹介します。あくまで@Controllerを使用し、@RestControllerは使用しません。

今回は「ユーザー情報」を扱うエンドポイントを例に、基本的なGET・POST・PUT・DELETEの動作を想定した設計です。開発環境はpleiadesで構築し、Gradleベースのプロジェクトを前提としています。


@Controller
@RequestMapping("/users")
public class UserController {

    @GetMapping
    public String listUsers(Model model) {
        // ユーザー一覧の取得
        return "user/list";
    }

    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id, Model model) {
        // 特定ユーザーの詳細取得
        return "user/detail";
    }

    @GetMapping("/new")
    public String showCreateForm(Model model) {
        // ユーザー作成フォーム表示
        model.addAttribute("user", new User());
        return "user/create";
    }

    @PostMapping
    public String createUser(@ModelAttribute User user) {
        // ユーザー新規登録処理
        return "redirect:/users";
    }

    @GetMapping("/{id}/edit")
    public String showEditForm(@PathVariable Long id, Model model) {
        // 編集フォームの表示処理
        return "user/edit";
    }

    @PostMapping("/{id}")
    public String updateUser(@PathVariable Long id, @ModelAttribute User user) {
        // 更新処理（実際はPUTが理想だがPOSTで対応）
        return "redirect:/users/" + id;
    }

    @PostMapping("/{id}/delete")
    public String deleteUser(@PathVariable Long id) {
        // 削除処理（DELETEではなくPOSTで対応）
        return "redirect:/users";
    }
}

このようにSpringでは、各エンドポイントに対応するメソッドを@GetMappingや@PostMappingで紐づけて実装します。

注意点：

PUTやDELETEはHTMLフォームから直接呼び出せないため、POSTで代用するのが一般的です。
リソース設計を意識し、/createUserや/deleteUserといった動詞を含むパスは避けています。
ファイル名の構成（例：user/detail.htmlなど）も、リソース名に揃えることで整合性が取れます。

この設計方針に従えば、REST APIの原則に沿った予測可能な設計が実現できます。Springとpleiadesを使えば、直感的にコントローラやルーティングの構築が可能となり、初心者でも扱いやすい構成になります。

まとめ

本記事では、REST APIにおけるリソース設計とエンドポイント設計について、初心者の方でも理解しやすいように、基礎から実践的な考え方までを順序立てて解説してきました。REST APIは、単にデータを取得したり更新したりするための仕組みではなく、設計そのものが非常に重要です。特にリソースをどのように定義し、URLとして表現するかによって、API全体の分かりやすさ、使いやすさ、そして将来的な拡張性や保守性が大きく変わってきます。

まず、REST APIの基本として「リソースは名詞で表現する」という原則を学びました。ユーザー、商品、注文といった対象となるデータは、すべてリソースとして扱い、その操作はHTTPメソッドで表現します。GETは取得、POSTは作成、PUTは更新、DELETEは削除という役割を持ち、URL自体に動詞を含めないことがRESTらしい設計につながります。この考え方を身につけることで、初めて見るエンドポイントであっても、何をするAPIなのかを直感的に理解できるようになります。

次に、エンドポイントの構造やURL設計の原則について解説しました。エンドポイントはシンプルで予測可能であることが重要です。たとえば「/users」「/products」といった複数形の名詞を使い、一覧取得や個別取得をパスパラメータで表現することで、一貫性のあるAPI設計が実現できます。また、ユーザーに紐づく注文情報のように、リソース同士の関係性をURLの階層構造で表すことで、データの関連性も自然に伝えられます。

パスパラメータとクエリパラメータの使い分けも重要なポイントです。特定のリソースを一意に指定する場合はパスパラメータを使い、一覧取得時の条件指定やページング、検索条件などにはクエリパラメータを使用します。この使い分けを意識することで、URLの意味が明確になり、API利用者にとって理解しやすい設計になります。

さらに、初心者が陥りやすい設計ミスとして、動詞を含むエンドポイントや、過度に複雑なURL構造についても触れました。一見わかりやすそうに見える「/getUser」や「/createOrder」といったURLは、RESTの思想から外れており、長期的にはメンテナンス性を下げる原因になります。常に「このURLは名詞だけで表現できているか」「他のエンドポイントと命名規則が揃っているか」を意識することが大切です。

Spring MVCを使った実装例では、@Controllerと各種Mappingアノテーションを用いて、REST APIの考え方をどのようにコードに落とし込むかを確認しました。HTMLフォームの制約によりPUTやDELETEが使えない場合でも、POSTで代用しつつ、URL設計自体はRESTの原則を守ることで、全体として一貫性のある構成を保つことができます。ファイル構成やテンプレート名をリソース名に合わせることも、設計を分かりやすくする工夫のひとつです。

REST APIのリソース設計とエンドポイント設計は、一度身につければ、どのようなWebアプリケーション開発にも応用できる重要な考え方です。シンプルで読みやすく、予測可能なAPIを意識することで、開発者自身だけでなく、将来そのAPIを使う他の開発者にとっても優しい設計になります。今回学んだポイントを意識しながら、実際に手を動かして設計や実装を行うことで、理解はさらに深まっていくでしょう。

まとめとしてのサンプルエンドポイント設計


GET /articles            // 記事一覧の取得
GET /articles/3          // IDが3の記事を取得
POST /articles           // 新しい記事を作成
PUT /articles/3          // IDが3の記事を更新
DELETE /articles/3       // IDが3の記事を削除

上記のように、URLは常に名詞で表現され、操作の内容はHTTPメソッドによって判断できる構成になっています。この形を基本として考えることで、REST APIとして自然で分かりやすい設計が可能になります。

先生と生徒の振り返り会話

生徒：「REST APIって、最初はただのURLの決め方だと思っていましたけど、リソース設計がこんなに大事なんですね。」

先生：「そうだね。リソース設計はAPI全体の設計図みたいなものだから、ここがしっかりしていると後がとても楽になるよ。」

生徒：「動詞を使わずに名詞でURLを作る、というのも最初は不思議でしたけど、慣れると分かりやすいですね。」

先生：「HTTPメソッドと役割分担できているから、URLがシンプルになるんだ。RESTらしさは、そのシンプルさにあるんだよ。」

生徒：「パスパラメータとクエリパラメータの使い分けも、実際のURLを見ると理解できました。」

先生：「うん。その違いを意識できるようになると、設計の質が一段上がるね。」

生徒：「Springでの実装例もあったので、実際のコードと結びつけて考えられました。」

先生：「設計と実装をセットで考えるのが大事だよ。これからAPIを作るときは、まずリソース設計から考えてみよう。」

生徒：「はい。これからは、予測しやすくて一貫性のあるREST APIを意識して設計してみます。」