はじめに

こんにちは、くらっちです。
最近仕事でAPIの設計に携わることになり、REST APIについて色々調べたのでまとめました。
私個人のメモですが、皆さんのお役に立てばうれしいです✨

REST APIとは

API は 2つのアプリケーション（システム間）で情報をやり取りするための窓口 です。
API を通してDBにデータを登録・更新・取得・削除したり、他アプリのデータ処理を行うことができます。

REST API は下記の「RESTの原則」に従って設計された API です。
REST API は統一インターフェース、アドレス可能性、ステートレス、接続性という特徴を持っていて、クライアントとサーバー間の通信は『HTTP』を介して行われます。
「RESTの原則」を満たしていない API は REST API とは言わず、Web API などと呼びます。

RESTの原則

1. 統一インターフェース

統一された方法で通信を行います。
処理の内容に応じてインターフェース（HTTPメソッド）が決まっています。

「データの登録」は「POST」
「データの更新」は「PUT」
「データの取得」は「GET」
「データの削除」は「DELETE」です。

2. アドレス可能性

下記のように必ず一意のURLを持っており、URLを指定することで特定のリソースにアクセスできます。

例１：https://xxxxxx.co.jp/v1.0/users
例２：https://xxxxxx.co.jp/v1.0/users?country=Japan

3. ステートレス

ステートは「状態」を表し、ステートレスは「状態がない」と表せます。
「状態がない」＝「サーバー側はクライアントとの通信情報を保持しない」と言えます。
サーバー側はクライアントとの通信情報を保持しないため、リクエストの度にすべての情報を送らないといけません。

REST API がステートレスであるのは下記のような理由があります。
- アプリケーションの状態を覚える必要がないため、サーバ側のシステムは単純になる
- サーバ資源をすぐに開放できるという利点があり、負荷軽減や操作性が向上する

4. 接続性

リクエストとレスポンスの情報にリンクを含めることができます。
そのリンクはリソースへのアクセスや関連するリソースを参照するために使用されます。
リソースに接続して必要な処理を行うのです。

REST APIの構成

REST API は、HTTPメソッドとURIの組み合わせで構成されています。

HTTPメソッド

APIを呼び出すときに必要な操作の種類（インターフェース）のことです。
具体的には下記のようなものがあります。
GET（データ取得）、POST（データ登録）、PUT（データ更新）、DELETE（データ削除）

URI（Uniform Resource Identiier）

URIとは「Web APIを利用するためのURL」のことです。
下図のように「プロトコル」「ドメイン」「パスパラメータ」の組み合わせで構成されます。

リクエストとレスポンス

リクエスト

リクエストヘッダー

リクエストの詳細情報をサーバーに伝えます。
APIを呼び出すために必要な情報でリクエストの内容や形式、認証情報などを指定します。

主な情報
　クライアント情報
　　・User-Agent：クライアントのソフトウェア名やバージョン
　　・Accept-Language：クライアントの使用言語設定
　リクエストのメタデータ
　　・Content-Type：リクエストボディのデータ形式
　　・Content-Length：リクエストボディの長さ（バイト数）
　認証/認可情報
　　・Authorization：認証トークンやAPIキー等
　APIの指定
　　・Accept：受け入れ可能なレスポンスのデータ形式

ボディ

ボディはリクエストの本文です。
実際に送信するデータ本体であり、JSONなどの構造化データを渡します。

ヘッダーとボディを含めたリクエストの形式はこのような形になります。

POST /api/members HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: [バイト数]
Authorization: Bearer [トークン]

[JSONデータ]

具体例：members情報をPOSTする場合

POST /api/members HTTP/1.1 
Host: example.com
Content-Type: application/json
Content-Length: 236
Authorization: Bearer f47ac10b-58cc-4372-a567-0e02b2c3d479

{
    "members":[
        {
            "member_name": "tanaka_taro",
            "member_address": "東京都板橋区○○ 111-111-111",
            "member_telephone": "090-1111-2222",
            "member_hobby":[
                {
                    "hobby_id": 1,
                    "hobby_name": "将棋"
                },
                {
                    "hobby_id": 2,
                    "hobby_name": "サッカー"
                }
            ]
        }
    ]
}

レスポンス

リクエストのあと、サーバー側の処理の結果をAPI経由で受け取ります。
受け取る情報の形式や内容を定義する必要があります。

レスポンス例：GET 成功時

HTTP/1.1 200 OK
Content-Type: application/json

{
　"members": [
　　{
　　    "id": 1,
    　　"name": "John Doe",
    　　"email": "john.doe@example.com"
　　},
　　{
　　    "id": 2,
    　　"name": "Sam Ocean",
    　　"email": "sam.ocean@example.com"
　　},
　]
}

レスポンス例：POST 成功時

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 2,
    "name": "Alice",
    "email": "alice@example.com"
}

レスポンス例：PUT 成功時

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 2,
    "name": "Alice Smith",
    "email": "alice.smith@example.com"
}

レスポンス例：DELETE 成功時

HTTP/1.1 204 No Content

HTTP ステータスコード

HTTPステータスコードは、リクエストの結果を示すコードでHTTPプロトコルの一部として定義されています。
リクエストが正常終了した、エラーが発生した、または他のアクションが必要かを通知します。

Code	意味	説明
200	OK	正常終了
204	No Content	正常終了したが返す値はなし
400	Bad Request	リクエストが不正（バリデーションエラーなど）
401	Unauthorized	認証が必要
403	Forbidden	リクエスト拒否（権限なし）
404	Not Found	リソースが見つからない
500	Internal Server Error	サーバーの内部エラーが発生。設定ミス、リソース不足など
502	Bad Gateway	サーバー間の通信で発生した問題

参考

REST入門基礎知識
 ステートレスとは何か
 REST APIとは何か？初心者にもわかりやすく解説します！
【図解】RESTful API とは何なのか【2024年版】

ランキング参加中

Windows開発者

くらっちのクラウド日記

仕事や勉強で得た Microsoft 365 関連の技術知識を投稿していくブログです。

【REST API】REST APIの基本を勉強しろ！調べた結果をまとめてみた