🦁

良いURI設計とは(エンドポイントの基本的な設計)#2

に公開

初めに

今回の記事は、WebAPIにおける良いURI設計について特に、以下についてまとめていきたいと思います。

  • HTTTPメソッドとエンドポイントについて
  • クエリパラメータにおける設計の注意点

第一弾目は以下の記事にまとめてます。
https://zenn.dev/daichi09167/articles/e833a0d9b050ab

HTTTPメソッドとエンドポイントについて

エンドポイントとは、APIが提供する特定のリソースにアクセスするためのURIです。HTTPメソッドは、そのエンドポイントに対してどのような操作を行うかをサーバーに指示します。

  1. GETメソッド
  • 特徴: サーバーからリソースを取得します。データの参照のみで、サーバー上のデータに変更を加えません。ブラウザでURLを入力してアクセスする際や、リンクをクリックする際に使用されます。
  • エンドポイント例:
    • /users (すべてのユーザーを取得)
    • /users/123 (IDが123のユーザーを取得)
    • /products?category=electronics&limit=10 (カテゴリがelectronicsの製品を10件取得)
  • 使用例: ウェブページを表示する、記事一覧を取得する、特定のユーザー情報を取得する。

  1. POSTメソッド
  • 特徴: サーバーに新しいリソースを作成します。 リクエストボディにデータを格納して送信します。
  • エンドポイント例:
    • /users (新しいユーザーを作成)
    • /products (新しい製品を作成)
  • 使用例: フォームの送信(ユーザー登録、コメント投稿)、新しい商品情報の登録。

  1. PUTメソッド
  • 特徴: 既存のリソースを完全に更新します。 指定されたURIにリソースが存在しない場合は、新しくリソースを作成します。
  • エンドポイント例:
    • /users/123 (IDが123のユーザー情報を完全に更新)
    • /products/abc (IDがabcの製品情報を完全に更新)
  • 使用例: 特定のブログ記事の内容を完全に置き換える、ユーザープロファイル全体を更新する。

  1. DELETEメソッド
  • 特徴: 指定されたリソースをサーバーから削除します。
  • エンドポイント例:
    • /users/123 (IDが123のユーザーを削除)
    • /products/abc (IDがabcの製品を削除)
  • 使用例: 特定のファイルを削除する、ユーザーアカウントを削除する。

  1. PATCHメソッド
  • 特徴: 既存のリソースの一部を更新します(部分的な更新)。リクエストボディに、更新したい部分のデータのみを含めます。
  • エンドポイント例:
    • /users/123 (IDが123のユーザーの名前だけを更新)
  • 使用例: ユーザーのメールアドレスのみを変更する、記事のタイトルだけを修正する。

  1. HEADメソッド
  • 特徴: GETリクエストと同じヘッダー情報を取得しますが、レスポンスボディは含みません。

  • エンドポイント例:

    • /users/123 (IDが123のユーザー情報のヘッダーのみを取得)
  • 使用例: ファイルのサイズを確認せずにダウンロードの可否を判断する、キャッシュの有効性を確認する。

PUTとPOSTの違い

以下に違いをまとめます。

  • 「新しいリソースを作るとき → POST」
  • 「既にあるリソースを修正するとき → PUT」

クエリパラメータにおける設計の注意点

  1. 相対位置を利用するメリットデメリット
    相対位置とは、現在のページを基準として次のページや前のページを指定する方法です。例えば、 page=nextpage=prev のような形式が該当します
  • メリット:

    • 実装が比較的シンプルで、ユーザーインターフェースも直感的になります。「次へ」「前へ」ボタンのような操作に適しています。
  • デメリット:

    • 特定のページに直接アクセスすることができません。ブックマークや共有には不向きです。
    • 多数のページがある場合、一気に目的のページにジャンプすることができません。

  1. 絶対位置を利用するメリットデメリット
    絶対位置とは、ページ番号やアイテムのIDなど、具体的な位置を示す情報を利用する方法です。例えば、page=3offset=100 のような形式が該当します。
  • メリット:
    • 特定のページに直接アクセスできるため、ブックマークや共有に適しています。
    • 多数のページがある場合でも、目的のページに一気にジャンプできます。
    • クライアント側で現在のページ番号を保持すればよいため、サーバー側の状態管理が簡素化されます。
  • デメリット:
    • 無効なページ番号: 存在しないページ番号が指定された場合のハンドリングが必要です。

  1. 絞り込みにおける注意点
    クエリパラメータで絞り込み条件を指定する際に気をつけたい点を以下にまとめます。
  • パラメータ名の明確化: 絞り込み条件を表すパラメータ名は、その意図が明確にわかるように命名します(例: category=electronics, price_min=1000, color=red)。
  • 値のフォーマット: 値のフォーマットを統一し、適切にバリデーションを行います(例: 日付はISO 8601形式、数値は整数/浮動小数点数など)。
ISO 8601形式ってなーに

以下に詳しくまとめています!
https://zenn.dev/daichi09167/articles/de7de47cdf6797

  • 複数選択の考慮: 複数の値を許可する場合(例: 複数のカテゴリを選択)、配列形式(category[]=a&category[]=b)やカンマ区切り(category=a,b)など、扱いやすい形式を決定します。
  • デフォルト値の指定: パラメータが指定されない場合のデフォルト値を明確にします。
  • 組み合わせの複雑性: 複数の絞り込み条件が組み合わされた場合の論理(AND検索、OR検索)を明確にします。
  • エスケープ処理: クエリパラメータの値には、URLエンコードが必要な文字が含まれる可能性があるため、適切にエスケープ処理を行います。

  1. クエリパラメータとパスの使い分け
    • クエリパラメータ → リソースのフィルタリング、ソート、ページングなど: リソースに対する追加情報や操作を表すために使われます。
    • パス → 特定のリソースを一意に識別するために使われます。階層構造を表すのに適しています。

  1. offset,limitの使い分け
    offset と limit は、データの一部分を取得する(ページングする)ための一般的なクエリパラメータです。
  • limit (取得件数): 一度に取得するレコードの最大数を指定します。
    • 例: limit=10 (10件取得)
  • offset (開始位置): 取得を開始するレコードのオフセット(開始位置)を指定します。最初のレコードが0または1から始まるかはAPIの設計によります。
    • 例: offset=20 (20件目から取得)

Discussion