APIを設計するときに気を付けていること

RestAPI設計をするときに気をつけていることを殴り書きします

ちなみにAPI設計を綺麗に設計することにより下記のようなメリットがあります。

1. 使いやすい
2. 保守運用が容易
3. セキュリティリスクが下げることができる

WEB APIを美しく設計する重要性 - 世界一適当な技術ブログ

RESTの設計原則

RESTの設計原理をまずまとめます。設計原理を知らないとそもそも良い設計とは何かが理解できないです。

1. ステートレス(Stateless)

RESTではサーバ側で状態の管理を行わないのが基本です。 RESTで情報を持ちたい場合はクッキーとセッションを利用する

Cookieとセッションをまとめてみた。 - Qiita

2. 統一インターフェース(Uniform Interface)

RESTではリソースの処理をCRUD(GET/POST/PUT/DELETE)で処理する

API設計ステップ

対象となるデータを認識する
対象となるデータをリソースに分ける
リソースにURLで名前を付ける
リソースに対してGET/POST/PUT/DELETEをマッピングする
クライアントから受信する表現を設計する
クライアントに提供する表現を設計する
ハイパーメディアリングとフォームを使用して、既存のリソースと統合する(接続性を高める)
正常系を考える
例外条件を考える

API設計する上で気をつけること

1. 綺麗なURI（ルーティング）を作る

綺麗なURI（ルーティング）を作るときのTIPS - 世界一適当な技術ブログ

2.RESTful な URL にする

REST のキーとなる概念は、論理的に分割されたリソースを HTTP メソッド（GET, POST, PUT, PATCH, DELETE）で操作する、ということです。

GET /tickets - チケットのリストを取得する
GET /tickets/12 - 指定したチケットの情報を取得する
POST /tickets - 新しいチケットを作成する
PUT /tickets/12 - チケット #12 を更新する
PATCH /tickets/12 - チケット #12 を部分的に更新する
DELETE /tickets/12 - チケット #12 を削除する