Open3

API設計

engineer rebornengineer reborn

API設計

方針

  • 明確性と一貫性

    • 予測可能な動作、エラー、レスポンスのパターンを同じに

  • 拡張性

    • 柔軟なクエリ
      • ページネーションなど

  • セキュリティ

    • 認証・認可
    • サニタイズ
      • SQLインジェクションやXSS (クロスサイトスクリプティング) などの脆弱性から保護するため、すべての入力値を適切にサニタイズ

  • パフォーマンス

    • レスポンス速度
      • 100ミリ秒 (0.1秒) 以下:
        • 理想的
      • 100ミリ秒 ～ 300ミリ秒 (0.1秒 ～ 0.3秒):
        • 非常に良い: ユーザーはわずかな遅延を感じるかもしれませんが、操作の流れを妨げられることはほとんどありません
      • 300ミリ秒 ～ 1秒 (0.3秒 ～ 1秒):
        • 許容範囲: ユーザーは明確に遅延を感じ、イライラし始める可能性があります
          • Googleの調査などでは、読み込みに3秒以上かかるとユーザーの53%が離脱するというデータ
      • 3秒以上
        • 危険領域
      • バックグラウンドの場合
        • 1~5秒は許容
        • 数十秒以上はNG
    • キャッシュ
    • レートリミット
      • リクエスト条件
engineer rebornengineer reborn

基本機能

  • 認証

    • ヘッダー認証
      • Authorization
        • APIキー, JWT,Oauthトークン
    • クッキー認証 (Cookie-based Authentication)
      • 自動的に付与してくれるのは良いよね

  • レスポンス

    • ステータスコード
    • レスポンスボディ
      • 正常系: データ構造
      • 異常系:
        • エラーコード
        • エラーメッセージ
    • アプリケーションエラー

  • ログの吐き出し・通知(slack)

    • logger zerologなどで

  • 計測

    • newrelicなどで

  • レスポンスボディ

    • エラーの場合
// エラーレスポンスボディの例
{
  "code": "INVALID_INPUT",
  "message": "The provided email address is invalid.",
  "details": {
    "field": "email",
    "value": "invalid-email"
  }
}