RESTAPIのルーティングで気をつけることなんぞを。
直近のプロジェクトではRESTAPIを作ることが多かったんですが気をつけることなんぞを。
仕様書はソースから
web系のペースの早い現場とかだと、ドキュメントづくりが結構大変なんですよね。
上記のような問題点があるのですが、APIの場合は比較的ソースからドキュメントが起こしやすいのではないかと思います。
Laravelで作ったAPIのドキュメントを超簡単に生成する方法（Laravel API Documentation Generator）
私の場合、リクエストとレスポンスを伝えるのにテストコードを使っていました。
テストコードが仕様書になりますので、ソースの修正と同時に仕様書が出来上がります。(実際はそんなにうまく行きませんが手でドキュメントを作るよりかは差分が小さくなります。)
ツール
開発効率を上げるためにですが、APIを投げるツールについてよく調べておくこと
それほど調べたわけじゃないですが、やはりPostmanが使いやすかったです。
他curlコマンドを色々と応用したり、Guzzleなんかもツール化してみると使いやすいかと思います。
命名
今回のメインはここです。
命名ルールが場当たり的になってしまい、統一性がなくなることがありましたので、ある程度一般的なルールを学習したいと思います。
基本的な原則
- 言語の拡張子などを入れない
- http://exmample.com/api/v1/ などバージョンを入れる
- 名詞(できれば複数形)のみで構成するget,createなどを入れない(CRUDの分だけURLが増える)
- URLのみで情報がわかるようにする
実例(頻出のタイプに関して)
一覧系のメソッド(GET)+新規追加
http://example.com/api/v1/articles
個別参照(GET) + 個別編集(PUT)+削除(DELETE)
http://example.com/api/v1/articles/ID番号
などでしょうか。Laravelだと一気に作ることができます。
複雑なものは、
http://example.com/api/v1/customers/100/orders/200/comments/2
などのパターンが多いようです。(リンク参照)
上記だと、顧客ID100のお客さんの注文番号200の商品の２番目のコメントみたいな感じですかね。
