はじめに
- 業務でRESTful APIを作ったので、それを開発するまでの道のりを記載していきます。
- 今回はざっとRESTfulについて知った上で、プロジェクト向けにまずは自分なりに目的や概要などをざっくりと纏め直しました内容を記載します。
- 今後、もう少し突き詰めたAPIの仕様や設計内容などを書いていければとおもいます。
背景
- フレームワークの特性上、通常はMVC（VC）として疎結合な思想であるはずだが、現状の他の案件だと設計や実装フェーズでの切り離しが難しい。
- 上記のように拡張性が乏しいため、改修工数が肥大したり影響範囲が広くなってしまう。
- モデル層のテストが困難。現状、ほとんどが画面ベース（コントローラ層、ビュー層）のテストしか満たされていない。
- ビューの依存度が高いため、HTMLやほかのプロジェクトとの一元化が困難となってしまう。
- データを扱う非同期処理が複雑になってしまう。
- 目的に合わせて似たようなモジュールを作ったり、複製したり冗長になってしまう。
- 画面や機能に応じたリソースの俯瞰ができない。（どこに何の情報を利用しているのかが不明）
目的
拡張性や保守性を重視するために、RESTful APIを用いた構成にする。
RESTful思想の中で、特に以下のようなリソース志向を重要視する。
- プログラムはリソースが表現するURIにアクセスする。
- ステートレスにすることで追加改修などに対応した影響を抑えた拡張性を持たせる。
具体的に実施する内容
画面出力部とリソース処理部をプロジェクトベースで分離する
- 役割として明確にし、役割に応じた機能だけをそれぞれ実現する
情報のREAD／WRITEを一元的に集約し表現する
- URL＋パラメータで表現ルールを設定することで、柔軟かつ拡張的に情報へのアクセスが可能にする。
- イメージとしてはSolrのURL構造形式。
レスポンスをファイル形式にする
- 情報のレスポンスをファイル形式にすることで、プロジェクトやサービス、HTMLなどの静的ページを跨って利用できるようにする。
リクエストメソッドは以下の４種類に定義する
| # | リクエストメソッド | CRUD | 用途 |
|---|---|---|---|
| 1 | GET | READ | リソースの参照 |
| 2 | POST | CREATE | リソースの新規作成 |
| 3 | PUT | UPDATE | リソースの更新 |
| 4 | DELETE | DELETE | リソースの削除 |
URLの構成のルールについて
- URLに動詞を含まない。
- URLにadd/update/deleteを用いるのはリクエストメソッドと二重に意味を持たせるのでNG。
- URLにeditを用いるのは△（どうしてもというときのみ）。
- なるべく名詞に近づける（confirm→confirmation）。
例) GETの場合
× GET http://example.com/blog/getEntries
○ GET http://example.com/blog/entries
例) POSTの場合
× POST http://example.com/blog/entries/add
○ POST http://example.com/blog/entries
例) DELETEの場合
× POST http://example.com/blog/entries/30/delete
○ DELETE http://example.com/blog/entries/30
擬似静的化URLとパラメータの役割
例) http://example.com/blog/entries?page3=&lang=ja
擬似静的化URL
リソースの意味や場所を示す
http://example.com/blog/entries
パラメータ
クライアント側の意思に基づく選択肢を示す
?page3=&lang=ja
ステータスコードのルール
- 意識的に仕様するコードは概ね次のものに収束する。
- クライアント側が悪い場合は400系のステータスコードを用いる。
- サーバ側が悪い場合は500系のステータスコードを用いる。
200系
200 201 204
300系
301 303 307 (304)
400系
400 404 409 (401,403)
500系
500