API

Swagger API(REST API)とDB定義チェック表

 

API・DB設計でレビュー頂いた数々を大公開…。😭😭😭

 

Swagger Editor API設計

 

 

現在要件にないものはAPI設計に含めない

YAGNIの法則。

将来の拡張を見越して作っておいちゃえ!っと含めるとアプリ開発側で謎のエンドポイントや属性になる😥

現在の要件のみAPI設計に含める

 

キャメルケース、パスカルケースの混在

 

  • キャメルケース
    /refreshToken
  • パスカルケース(ケバブケース, お団子ケース)
    /refresh-token

どちらかに統一すること。混在はだめ!

 

GETパラメータなしのエンドポイントの400

 

  • GETのアクセスかつパラメータもないのに、400(BadRequest)はありえない。
  • Swaggerの設計に加えてはいけない

 

ユーザが自由入力しないのに400は設定しない

  • 既読
  • お気に入り登録、削除
  • 退会

の送信など。

アプリ側での送信によるものは400(BadRequest)は設定しない。

 

  • プロフィールの編集
  • パスワードの登録変更

ユーザの自由入力が伴うものに対して400を設定する

 

既読送信

 

お気に入り送信

 

 

 

配列の中に配列!?

 

このまま書くと配列の中に配列が発生。。

😃

こうする。

レファレンス先で定義しておくこと。

 

セキュリティの認証のあり、なし

 

security: []は認証なしでアクセスできるものを表す。

 

  • /loginならこのsecurity: []を記述して認証を無効化する必要がある
  • /userme/profileならsecurity: []は記述しない
    会員情報をログインせずにアクセスできたらおかしい。

 

WEBがある場合

  • WEBで公開されている情報を取得するエンドポイントは認証をつけてはいけない

 

一件だけ取得した場合にも配列で返すのか?

 

サーバスタータス 200と204の使い分け

すべて200にしていないか?

  • アクセスしてresponseBodyを返却するサーバスタース
    → 200
  • 更新処理などで成功かつresponseBodyは返さないサーバステータス
    → 204

@see

 

エラーコード

  • 400: BadRequest
    リクエストが不正または異常です。
  • 401: UnAuthorized
    未認証、または権限がありません。
  • 403: Forbidden
    紐づけられていない会員IDです
  • 404: NotFound
    エンドポイントがありません
  • 500: ServerError
    サーバサイドエラー

 

ログインが必要のないエンドポイントで401エラーのレスポンスがある

 

 

必須な要素であればrequiredをつける

 

https://swagger.io/docs/specification/data-models/data-types/

 

レスポンスで利用しない属性を返してしまっている

最小限の情報を返すように設計しましょう。

 

requestBodyで送ってはいけない属性をオブジェクトに設定してしまっている

  • パスワード

    ・ログインの時のみに送る。
    ・汎用のプロフィールオブジェクトで送るのはおかしい。
  • 通貨, コイン, ポイント

    ・ユーザ側から送るのはおかしいので属性を持たない。
    ・サーバ側で処理してレスポンスのみ受け取るようにする
  • 画像URL

    Multipart Requestsで画像そのものを送信するのが普通

 

 

 

 enumの不使用

定型的に決まっている値を返すならenum型を利用する

  • 使う文字列決まってるならenumが使える
  • タイプや追加予定のないカテゴリーなど

 

enumを利用したActivityスキーマの例

 

 

履歴のオブジェクトで日時を返していない

  • 表示で日付がなくても忘れずに。
  • アプリ側で利用する

 

JSONのboolean型はtrue/false

 

TINYINT(0, 1)ではない。

 

datetimeのフォーマットは書式も書く

 

これ

 

 

お気に入りやチェックインみたいなスイッチタイプのものはエンドポイントは1つ

 

 

 

 

 

 

multipart/form-dataだとstringしか使えない & nullを使えない

 

ここポイント

 

@see

https://swagger.io/docs/specification/describing-request-body/multipart-requests/

 

DB定義 マイグレーションファイル

 

deleted_atでデリートフラグ

  • Laravelであれば『delete_flag』はいらない。
  • deleted_atだけで良い。

 

複合プライマリキー

複合プライマリキーのテーブルなら、きちんとマイグレーションファイルで定義する。

 

フラグ関連のテーブル

Boolean型かつデフォルトを0に設定する。

 

 

 

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

日本語が含まれない投稿は無視されますのでご注意ください。(スパム対策)