【初学者向け】RESTful APIとは？

はじめに

Webアプリを作っていると、「RESTful API」という言葉をよく見かけます。
なんとなく使っていた言葉ですが、正しく認識できるように、改めてまとめてみました。

この記事では、

• RESTとは何か
• RESTful APIの考え方
• APIエンドポイントとの関係
• 実際のAPI例

を初心者向けに整理してみます。

RESTとは

RESTは

Representational State Transfer

の略で、Web APIを設計するための設計思想です。

重要なのは
「こういうルールでAPIを作ると、わかりやすくて拡張しやすい」
という設計の考え方であることです。

RESTでは特に次のような考え方が重要になります。

• URLはリソース（データ）を表す
• HTTPメソッドで操作を表す
• ステートレスである
• 統一されたインターフェースを持つ

RESTful APIとは

RESTの考え方に沿って作られたAPIをRESTful APIと呼びます。

つまり

RESTful API = RESTのルールに沿ったAPI

という意味です。

RESTful APIの基本構造

RESTful APIではURLはリソース（データ）を表すように設計します。

例えば「記事」を扱うAPIの場合

/articles
/articles/1

このようになります。

HTTPメソッドで操作を表す

RESTful APIでは、URLではなくHTTPメソッドで操作を表します。

操作	HTTPメソッド	URL
一覧取得	GET	/articles
詳細取得	GET	/articles/1
作成	POST	/articles
更新	PATCH / PUT	/articles/1
削除	DELETE	/articles/1

例えば

• 記事一覧を取得

  GET /articles
  

• 記事を作成

  POST /articles
  

• 記事を削除

  DELETE /articles/1
  

このように、URLは同じでもHTTPメソッドで意味が変わるのがRESTの特徴です。

RESTful APIの基本ルール

RESTful APIにはいくつかの設計ルールがありますが、特に重要なのが次の2つです。

• URLはリソース（データ名）を表す
• URLは名詞で表す（動詞は使わない）

URLは名詞で書く

RESTful APIでは、URLに
動詞ではなく名詞を書く
というルールがあります。

これは
URL = データ
HTTPメソッド = 操作
という役割分担があるためです。

良くない例（動詞を使っている）

/getArticles
/createArticle
/deleteArticle

この書き方だと

• URLが操作を表している
• HTTPメソッドの意味と重複する

という問題があります。

RESTfulな書き方（名詞を使っている）

/articles
/articles/1

URLで使われるリソースは名詞にするのが鉄則。
そして、操作は(GET POST PATCH DELETEなどの)HTTPメソッドで表します。

URLは名詞で表す（動詞は使わない）

APIエンドポイントとは

APIの中でも、アクセスできるURLのことをエンドポイントと呼びます。

例えば

GET /api/v1/articles

この場合

/api/v1/articles

がエンドポイントです。

つまり

• API：機能全体
• エンドポイント：個別のURL

という関係になります。

実際のAPIレスポンス例

例えば、記事一覧APIの場合

• リクエスト

  GET /api/v1/articles
  

• レスポンス

  {
    "articles": [
      {
        "id": 1,
        "title": "REST APIとは",
        "author": "user1"
      },
      {
        "id": 2,
        "title": "Rails API設計",
        "author": "user2"
      }
    ]
  }
  

フロントエンドはこのJSONを受け取って画面を表示します。

ネストされたリソース

RESTでは、リソース同士の関係を**ネスト（階層）**で表すこともあります。

例：

/books/:book_id/chapters/:chapter_id

このようなURLがある場合、例えば

GET /books/harry-potter/chapters/3

これは

• harry-potter という本
• その3章

という関係を表しています。

このようにデータの関係性をURLで表現できるのもRESTの特徴です。

RESTful APIのメリット

RESTful APIには次のようなメリットがあります。

1. ルールが統一される
   設計ルールがあるため、読みやすく理解しやすいAPIになります。

2. フロントエンドとバックエンドを分離できる
   例えば、
   フロント：React
   バックエンド：Rails API
   のように分けても、JSONで通信すれば問題なく動きます。

3. 拡張しやすい
   RESTのルールに沿っていれば、新しい機能を追加するときも

/articles
/comments
/users

のように整理して増やしていけます。

まとめ

RESTful APIは
Web APIを分かりやすく設計するためのルール
です。

ポイントをまとめると

• URLは名詞で表す
• HTTPメソッドで操作を表す
• APIのURLをエンドポイントと呼ぶ
• JSONでデータを返すことが多い

RailsでAPIを作る場合も、このRESTの考え方が基本になっています。