世界一適当な技術ブログ

日々学んだ内容をとにかくにブログ形式でアウトプットします。(技術系中心)基本自分用備忘録です。

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

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設計ステップ

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

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 を削除する

3.バージョンはURLに含めれる

バージョン管理をすることで、メジャーアップデートがあるような場合は移行期間として過去バージョンと共存させるなど、滑らかな改修作業が可能になります。

4. フィルタ・ソート・検索はリクエストパラメータで対応する

ベースとなる URL はできるだけシンプルにしておくのが良いです。

フィルタやソート、検索といった機能はリクエストパラメータで制御するのが良い(もっとも、これは単一リソースに絞るが)

1.フィルタリング

例)公開中のチケットのみを取得する

GET /tickets?state=open

2.ソート

例) チケットのリストを priority の降順で取得する

GET /tickets?sort=-priority

3.検索

例)最近クローズされたチケットを取得する

GET /tickets?state=closed&sort=-updated_at

参考

翻訳: WebAPI 設計のベストプラクティス - Qiita

RailsでREST API設計するときに知っておきたい集 - Qiita