API設計を学ぶ
合計時間：62時間 作業時間：4時間
ReactでAPIを利用するのだけど、設計をすることになった。 しかし、右も左も分からない状態だ。。 とりあえずは、以下のポイントがあると感じた。
- API設計(今回はRESTfulAPI)
- Swaggerの記述
参考にするプロジェクトのAPI設計を、 まず読めるレベルになる目標を持つ。 あとは、調べて比較した時の差分は現状質問するしかない。
RESTfulAPIの設計
SPA開発におけるWeb API設計入門（エンドポイント編）
所感
全体と詳細で分けた。
全体
- UI設計・API設計・DB設計(疎結合)
- エンドポイント：何を（リソース）どうする（HTTPメソッド） PATCHは使わない？
- 非同期通信ではHTMLの制約をうけないので、HTTPメソッドを適宜扱える（HTMLだと、GET,POSTのみに）
- リソースは、「モノ」だけでなく「コト」も
- 無意味なリソースがあるか、階層構造が適切か
- エラーメッセージをきちんと返そう
- HTTPステータスコードを活用しよう
- jsonはデフォルトで整形しよう（圧縮＋gzip）
クエリ・パス
- クエリパラメーター：任意（検索系）
- フィルタ・ソート・検索などを吸収する
- パスパラメーター：必須（個別リソースの特定） ※どちらでも表現できる場合は、要件次第
- versionはurlに含める
- パスは複数形が好ましい
- 基本は小文字（スネークケースorケバブケース）
- 関連データを埋め込む手段を作ろう
例
GET /tickets?sort=-priority # -は降順
GET /tickets?sort=-priority,created_at # ,はand
HTTPメソッド
- POST：複数回の実行でリソースが増える
- PUT：複数回の実行でリソースが増えない
- PATCH：一部更新
- 作成・更新後は変更後の情報をフルで返そう
- 作成・更新のリクエストボディにはjson(application/json)を使おう ※複数入力欄から一部更新がある場合は、PUTも一考すべき
レスポンスヘッダー
- ページング情報
- リクエスト制限情報
- キャッシュ情報
- Etag
- Last-Modified
Swagger
Swagger is 何
OpenAPIはRESTfulAPIを記述するためのフォーマット。 そして、OpenAPIをドキュメントとしてまとめるツールとしてSwaggerがある。 Swaggerにまつわる登場人物が結構多いので、 チュートリアルから攻めてイメージを掴んでみる。
OpenAPI (Swagger) 超入門 OpenAPI3.0のチュートリアルをやってみた
参考プロジェクトが3系なので、それに準じる。 以下の特性がある(3.0)
- ツリー構造になっている。
- ツリーにおいて特定の下層の関係性は決まっている
- ツリーの一部をグループにまとめることができる
確認方法(VSCode)
「Swagger-view」プラグインをインストール。 yamlファイルを開き、option+shift+pでビューが見える。 以下でredoc-static.htmlが生成される。
npx redoc-cli bundle swagger.yaml
まとめ
RESTfulAPIにおける登場人物と作法は、なんとなく分かった気がする。 素振りをする。
ほか
関係ないけど、netlifyでpackage-lock.jsonを含めるとビルドに失敗する、という教訓を得た。 Data-Dogってパフォーマンスツールだったのか。ログ系のツールかと思っていた。 DATA DOG