RESTful APIの設計ガイドライン

プロトコル

APIとユーザー間の通信プロトコルは、常にHTTPSを使用します。

ドメイン

APIは専用のサブドメインに配置することをお勧めします。

https://api.example.com

APIが非常にシンプルで将来的な拡張予定がない場合、主ドメイン下に配置することも可能です。

https://example.org/api/

バージョン管理

APIのバージョン番号はURLに含めるべきです。

https://api.example.com/v1/

HTTPヘッダーにバージョン情報を含める方法もありますが、URLに含める方が便利で直感的です。

エンドポイント

エンドポイントはAPIの具体的なURLを表し、リソースに対応します。RESTfulアーキテクチャでは、URLは動詞ではなく名詞を使用し、通常はデータベースのテーブル名に対応します。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

HTTPメソッド

リソースに対する操作は以下のHTTPメソッドで表現されます。

GET（SELECT）: サーバーからリソースを取得する。
POST（CREATE）: サーバー上に新しいリソースを作成する。
PUT（UPDATE）: サーバー上のリソースを更新する（クライアントが完全なリソース情報を提供）。
PATCH（UPDATE）: サーバー上のリソースを部分的に更新する。
DELETE（DELETE）: サーバー上のリソースを削除する。

その他のHTTPメソッド:

HEAD: リソースのメタデータを取得する。
OPTIONS: リソースのどの属性がクライアントによって変更可能かを取得する。

フィルタリング

多くのレコードがある場合、全てを返すのは現実的ではありません。APIはパラメータを使用して結果をフィルタリングできるようにすべきです。

?limit=10: 返されるレコード数を指定する。
?offset=10: 返されるレコードの開始位置を指定する。
?page=2&per_page=100: ページ番号と各ページのレコード数を指定する。
?sortby=name&order=asc: 並び順とソート順を指定する。
?animal_type_id=1: 絞り込み条件を指定する。

冗長性を許容し、APIパスとURLパラメータが重複することがあります。

ステータスコード

サーバーがユーザーに返すステータスコードとメッセージの例:

200 OK - [GET]: ユーザーのリクエストに成功した。
201 CREATED - [POST/PUT/PATCH]: 新しいデータが作成または更新された。
202 Accepted - [*]: リクエストがバックグラウンドキューに入っている。
204 NO CONTENT - [DELETE]: データが削除された。
400 INVALID REQUEST - [POST/PUT/PATCH]: リクエストが無効である。
401 Unauthorized - [*]: 認証情報が無効である。
403 Forbidden - [*]: アクセスが禁止されている。
404 NOT FOUND - [*]: リクエストされたリソースが存在しない。
406 Not Acceptable - [GET]: リクエストされた形式が利用できない。
410 Gone - [GET]: リクエストされたリソースが永久に削除された。
422 Unprocessable entity - [POST/PUT/PATCH]: バリデーションエラーが発生した。
500 INTERNAL SERVER ERROR - [*]: サーバー内部エラー。

エラーハンドリング

4xxステータスコードの場合、エラーメッセージをユーザーに返すべきです。

{
    "error": "Invalid API key"
}

レスポンスフォーマット

異なる操作に対して、サーバーがユーザーに返すべきレスポンス形式は以下の通りです。

GET /collection: リソースオブジェクトのリスト（配列）
GET /collection/resource: 単一のリソースオブジェクト
POST /collection: 新しく生成されたリソースオブジェクト
PUT /collection/resource: 完全なリソースオブジェクト
PATCH /collection/resource: 完全なリソースオブジェクト
DELETE /collection/resource: 空のドキュメント

Hypermedia API

RESTful APIはHypermedia APIとして設計され、レスポンスにリンクを含むことで、ユーザーが次のアクションを知ることができます。

{
  "link": {
    "rel": "collection https://www.example.com/zoos",
    "href": "https://api.example.com/zoos",
    "title": "List of zoos",
    "type": "application/vnd.yourformat+json"
  }
}

HATEOAS（Hypermedia as the Engine of Application State）デザインは、GitHub APIなどでも使用されています。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations"
}

その他

APIの認証にはOAuth 2.0フレームワークを使用する。
サーバーからのレスポンスデータ形式はJSONを使用することをお勧めします。

タグ: restful API HTTP JSON OAuth

6月7日 21:33 投稿

異端開発室