REST URI規約-作成中のリソースの単数形または複数形の名前

RESTは初めてですが、一部のRESTfulサービスでは、更新/取得/削除と作成に異なるリソースURIを使用していることがわかりました。といった

• 作成-使用/リソースを使用していくつかの場所で、POSTメソッド（複数の観察）で/リソースを（単数形）
• 更新-PUTメソッドで/ resource / 123を使用
• Get- GETメソッドで/ resource / 123を使用する

このURIの命名規則について少し混乱しています。リソースの作成には、複数形または単数形を何を使用すればよいですか？それを決定する際の基準は何ですか？

使用の前提/resourcesは、「すべての」リソースを表すことです。を実行するとGET /resources、コレクション全体が返される可能性があります。にPOSTすると/resources、コレクションに追加されます。

ただし、個々のリソースは/ resourceで利用できます。を実行するとGET /resource、このリクエストは意味を成さない/resource/123が完全に意味をなすため、エラーが発生する可能性があります。

の/resource代わりにを使用するの/resourcesは、たとえばファイルシステムとファイルのコレクションを操作/resourceしていて、その中に個別の123、456ファイルがある「ディレクトリ」である場合の方法と似ています。

どちらの方法も正しいか間違っている、あなたが一番好きなもので行きます。

私にとっては、コードに直接マッピングできるスキーマ（自動化が容易）を用意するのが良いです。これは、主にコードが両端にあるためです。

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

これを行う意味もわかりませんし、URIの設計としても最適ではないと思います。RESTfulサービスのユーザーとして、リストにアクセスするかリスト内の特定のリソースにアクセスするかに関係なく、リストリソースには同じ名前が付けられることを期待します。リストリソースを使用する場合でも、特定のリソースを使用する場合でも、同じ識別子を使用する必要があります。

複数

• シンプルな -すべてのURLは同じプレフィックスで始まります
• 論理 -orders/注文のインデックスリストを取得します。
• 標準 -最も広く採用されている標準の後に、圧倒的多数のパブリックおよびプライベートAPIが続きます。

例えば：

GET /resources -リソース項目のリストを返します

POST /resources -1つまたは複数のリソース項目を作成します

PUT /resources -1つまたは複数のリソース項目を更新します

PATCH /resources -1つまたは複数のリソースアイテムを部分的に更新します

DELETE /resources -すべてのリソースアイテムを削除します

単一のリソースアイテムの場合：

GET /resources/:id- :idパラメータに基づいて特定のリソース項目を返します

POST /resources/:id -指定されたIDで1つのリソース項目を作成します（検証が必要です）

PUT /resources/:id -特定のリソース項目を更新します

PATCH /resources/:id -特定のリソース項目を部分的に更新します

DELETE /resources/:id -特定のリソース項目を削除します

単数の擁護者にとっては、次のように考えてください。誰かにを頼んで、order1つのことを期待しますか、それともリストを期待しますか？では、入力したときにサービスが物事のリストを返すことを期待するのはなぜでしょう/orderか。

特異な

便利な ものは不規則な複数の名前を持つことができます。時々彼らは持っていない。しかし、単数形の名前は常にそこにあります。

例：CustomerAddressesに対するCustomerAddress

この関連リソースを検討してください。

これ/order/12/orderdetail/12はより読みやすく論理的です/orders/12/orderdetails/4。

データベーステーブル

リソースは、データベーステーブルのようなエンティティを表します。論理的な単数の名前が必要です。これが答えですがテーブル名です。

クラスマッピング

クラスは常に単数です。ORMツールは、クラス名と同じ名前のテーブルを生成します。使用されるツールが増えるにつれて、単数形の名前が標準になりつつあります。

REST API開発者のジレンマについてもっと読む

最も一般的な方法は複数形が使用されるRESTful APIですが/api/resources/123、たとえば、複数形の名前よりも単数形の名前の方が適切/表現力が高いと感じる特別なケースが1つあります。1対1の関係の場合です。具体的には、ターゲットアイテムが値オブジェクトである場合（ドメイン主導の設計パラダイム）。

すべてのリソースが1対1でaccessLogあり、値オブジェクトとしてモデル化できると想定します。つまり、エンティティではないため、IDはありません。それはとして表現することができます/api/resources/123/accessLog。通常の動詞（POST、PUT、DELETE、GET）は、意図が適切に表現され、関係が実際に1対1であるという事実も適切に表現します。

単数形が一般に受け入れられている、データベーステーブル名の一般的な傾向に従ってみませんか？そこに行って、それをやりました。再利用しましょう。

テーブル命名のジレンマ：単数名と複数名

こんなに多くの人が複数形の名詞バンドワゴンに飛び乗るのを見て驚いた。単数形から複数形への変換を実装する場合、不規則な複数名詞を扱いますか？あなたは痛みを楽しんでいますか？

http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htmを参照して ください

不規則な複数形には多くの種類がありますが、これらは最も一般的です。

名詞型複数形の例

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

APIコンシューマーの観点から、エンドポイントは予測可能である必要があります

理想的には...

1. GET /resources リソースのリストを返す必要があります。
2. GET /resource 400レベルのステータスコードを返す必要があります。
3. GET /resources/id/{resourceId} 1つのリソースを持つコレクションを返す必要があります。
4. GET /resource/id/{resourceId} リソースオブジェクトを返す必要があります。
5. POST /resources リソースをバッチ作成する必要があります。
6. POST /resource リソースを作成する必要があります。
7. PUT /resource リソースオブジェクトを更新する必要があります。
8. PATCH /resource 変更された属性のみを投稿して、リソースを更新する必要があります。
9. PATCH /resources 変更された属性のみをポストするリソースをバッチ更新する必要があります。
10. DELETE /resourcesすべてのリソースを削除する必要があります。冗談：400ステータスコード
11. DELETE /resource/id/{resourceId}

このアプローチは最も柔軟で機能が豊富ですが、開発に最も時間がかかります。したがって、急いでいる場合は（ソフトウェア開発では常にそうです）、エンドポイントresourceまたは複数形に名前を付けますresources。すべての複数形が「s」で終わるわけではないため、プログラムで内省して評価するオプションを提供するため、私は単数形を好みます。

とはいえ、最も一般的に使用されているプラ​​クティス開発者が選択した理由は何であれ、複数形を使用することです。これが最終的に私が選択したルートです。githubそしてtwitter、やのような人気のあるAPIを見ると、これが彼らのしていることです。

決定するためのいくつかの基準は次のとおりです。

1. 時間の制約は何ですか？
2. 消費者にどのような操作を許可しますか？
3. リクエストと結果のペイロードはどのように見えますか？
4. コードでリフレクションを使用してURIを解析できるようにしたいですか？

だから、それはあなた次第です。一貫性のあることなら何でも。

私の2セント：時間を複数から単数またはその逆に変更する方法を費やすメソッドは、CPUサイクルの無駄です。私は古い学校かもしれませんが、私の時代には物事は同じと呼ばれていました。人に関するメソッドを検索するにはどうすればよいですか？通常の表現は、望ましくない副作用なしに人と人の両方をカバーしません。

英語の複数形は非常に恣意的であり、コードを不必要に邪魔します。1つの命名規則に従ってください。コンピュータ言語は、自然言語を模倣することではなく、数学的な明快さについてであるはずでした。

単純さと一貫性の両方のために、単数形を使用することを好みます。

たとえば、次のURLを考えてみます。

/ customer / 1

私は顧客を顧客の集まりとして扱いますが、簡単にするために、集荷部分は削除されています。

もう一つの例：

/ equipment / 1

この場合、機器は正しい複数形ではありません。したがって、それを機器のコレクションとして扱い、簡単にするためにコレクションを削除すると、顧客のケースとの一貫性が保たれます。

ルートのIDはリストのインデックスと同じように表示され、それに応じて命名が行われる必要があります。

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

しかし、一部のリソースはルートにIDを使用しません。これは、1つしか存在しないか、ユーザーが2つ以上にアクセスできないため、リストではないためです。

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

命名規則を使用すると、通常は「1つだけ選択してそれを守る」と言っても安全です。

ただし、RESTを多くの人に説明する必要があるため、エンドポイントをファイルシステム上のパスとして表すことが最も表現力のある方法です。
ステートレス（ファイルが存在するか存在しないかのどちらか）、階層的、シンプル、そして使い慣れたものです。ローカルでもhttpでも、静的ファイルにアクセスする方法はすでに知っています。

そして、その文脈の中で、言語規則は次の範囲でのみあなたを得ることができます：

ディレクトリには複数のファイルやサブディレクトリを含めることができるため、その名前は複数形にするがあります。

そして私はそれが好きです。
一方、それはあなたのディレクトリですが、それが必要な場合は、「a-resource-or-multiple-resources」という名前を付けることができます。それは本当に重要なことではありません。

重要なのは、「123」という名前のファイルを「resourceS」という名前のディレクトリの下に置くと、 /resourceS/123）、にからアクセスできると期待できないことです/resource/123。

必要以上にスマートにしようとしないでください。現在アクセスしているリソースの数に応じて複数から単数に変更することは、見た目が良い場合もありますが、効果がなく、意味がありません。 階層システム。

注：技術的には、「シンボリックリンク」を作成できるため、から/resources/123もアクセスできます/resource/123が、前者はまだ存在している必要があります。

見ていグーグルのAPI設計ガイドを：リソース名に関する別をご覧ください。

要するに：

• コレクションは複数形で名前が付けられます。
• 個々のリソースには文字列が付けられます。

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

あなたがこの主題について考えているなら、それは読む価値があります。

すべてのメソッドに複数を使用することは、少なくとも1つの側面でより実用的です。Postman（または同様のツール）を使用してリソースAPIを開発およびテストしている場合、GETからPUTにPOSTなどに切り替えるときにURIを編集する必要はありません。 。

どちらの表現も役立ちます。私はかなり前から便宜上単数形を使用していましたが、活用は難しい場合があります。厳密に単一のREST APIを開発した私の経験では、エンドポイントを使用する開発者は、結果の形がどうなるかについて確信を持っていません。今では、応答の形を最もよく表す用語を使用することを好みます。

すべてのリソースが最上位レベルである場合は、特異な表現で回避できます。抑揚を回避することは大きな勝利です。

リレーションに対するクエリを表すために何らかのディープリンクを実行している場合、APIを作成する開発者は、より厳密な規則を持つことで支援できます。

私の慣習では、URIの各レベルの深さは親リソースとの相互作用を記述しており、完全なURIは何が取得されるかを暗黙的に記述している必要があります。

次のモデルがあるとします。

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

クライアントが特定のユーザーの特定の友達のマネージャーを取得できるリソースを提供する必要がある場合は、次のようになります。

GET /users/{id}/friends/{friendId}/manager

次に、いくつかの例を示します。

• GET /users -グローバルユーザーコレクションのユーザーリソースを一覧表示する
• POST /users -グローバルユーザーコレクションに新しいユーザーを作成する
• GET /users/{id} -グローバルユーザーコレクションから特定のユーザーを取得する
• GET /users/{id}/manager -特定のユーザーのマネージャーを取得する
• GET /users/{id}/friends -ユーザーの友達のリストを取得する
• GET /users/{id}/friends/{friendId} -ユーザーの特定の友達を取得する
• LINK /users/{id}/friends -このユーザーに友達の関連付けを追加する
• UNLINK /users/{id}/friends -このユーザーから友達の関連付けを削除します

各レベルが、アクションを実行できる親にどのようにマップされているかに注目してください。同じオブジェクトに異なる親を使用することは直観に反します。でリソースを取得してもGET /resource/123、新しいリソースの作成がPOST /resources

私はほとんどの人が複数を使用するか単数を使用するかを決定する間にいることを知っています。ここで対処されていない問題は、クライアントがどちらを使用しているかを知る必要があり、常に間違いを犯す可能性が高いことです。これが私の提案の出所です。

両方はどうですか？つまり、API全体に単数形を使用し、複数形で行われたリクエストを単数形に転送するルートを作成することを意味します。例えば：

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

あなたは写真を取得します。誰も間違っていない、最小限の努力、そしてクライアントは常にそれを正しく理解するでしょう。

{id}URL の一部がサブリソースと重複することを、id理論的には何でも可能であり、あいまいさがある。異なる概念（識別子とサブリソース名）が混在しています。

同様の問題は、enum定数やフォルダー構造でよく見られます。ここでは、異なる概念が混在しています（たとえば、フォルダーTigers、LionsおよびCheetahsがあり、さらにAnimalsと同じレベルでは- 1でのサブセットであるとして、これは意味がありませんその他）。

一般に、エンドポイントの最後に指定された部分は、一度に1つのエンティティを処理する場合は単数であり、エンティティのリストを処理する場合は複数である必要があると思います。

したがって、単一のユーザーを扱うエンドポイント：

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

次に、ユーザーに対してクエリを実行するための別のリソースがあり、通常はリストを返します。

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

そして、特定のユーザーを扱うサブリソースのいくつかの例：

GET /user/{id}/friends -> Returns a list of friends of given user

友達を作る（多対多リンク）：

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

あいまいさはなく、リソースの複数形または単数形の名前は、ユーザーが期待できるもの（リストまたはオブジェクト）のヒントになります。idsには制限がなく、理論的にnewは（将来の）サブリソース名と重複することなく、IDを持つユーザーを作成できます。

Singularを使用して、「ビジネスディレクトリ」などで見られる英語の慣習を活用してください。

「ブックケース」、「ドッグパック」、「アートギャラリー」、「映画祭」、「車のロット」など、多くのものがこのように読みます。

これは、URLパスを左から右に一致させるのに便利です。左のアイテムタイプ。右のタイプを設定します。

GET /users本当に今までのユーザーのセットをフェッチ？通常はありません。キーとユーザー名を含む一連のスタブをフェッチします。だから/usersとにかく、そうではありません。これは、ユーザーのインデックス、または「ユーザーインデックス」です。それをそれと呼ばないのはなぜですか？それは/user/indexです。私たちは、セットタイプを命名しましたので、私たちは、クエリパラメータなどに頼ることなく、ユーザーのさまざまな投影を示す複数のタイプを持つことができますuser/phone-listか/user/mailing-list。

そして、ユーザー300はどうですか？それはまだ/user/300です。

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

最後に、HTTPは1つの要求に対して1つの応答しか持てません。パスは常に単一の何かを指します。

私にとって、複数はコレクションを操作しますが、単数はコレクション内のアイテムを操作します。

コレクションはメソッドGET / POST / DELETEを許可します

アイテムはメソッドGET / PUT / DELETEを許可します

例えば

/ studentsに対するPOST は、学校に新しい生徒を追加します。

/ studentsで DELETE を実行すると、学校のすべての生徒が削除されます。

/ student / 123で DELETEを実行すると、生徒123が学校から削除されます。

重要ではないように感じるかもしれませんが、一部のエンジニアはIDを忘れることがあります。ルートが常に複数でDELETEを実行した場合、誤ってデータを消去してしまう可能性があります。一方、単数形のIDがない場合は、404ルートが見つかりません。

APIが複数の学校を公開することになっている場合の例をさらに拡張するには、次のようなもの

/ school / abc / studentsで DELETE を実行すると、学校のすべての生徒が削除されますabc。

正しい単語を選択すること自体が難しい場合もありますが、コレクションでは複数を維持するのが好きです。たとえばcart_items、cart/items正しいと感じます。cart削除とは対照的に、カート内のアイテムではなく、カートオブジェクト自体を削除します;）。

どうですか：

/resource/（ではない/resource）

/resource/ 「リソース」と呼ばれるものが含まれているフォルダであることを意味します。これは「リソース」フォルダです。

また、データベーステーブルの命名規則も同じだと思います。たとえば、「user」というテーブルは「userテーブル」であり、「user」という名前のものが含まれています。

私は複数形（/resources）と単数形（/resource/{id}）のこれは、リソースのコレクションでの作業と単一のリソースでの作業の間のロジックをより明確に分離するためです。

これの重要な副作用として、誰かがAPIを誤って使用するのを防ぐこともできます。たとえば、ユーザーが次のようにパラメーターとしてIDを指定してリソースを誤って取得しようとした場合を考えてみます。

GET /resources?Id=123

この場合、複数形バージョンを使用すると、サーバーはIdパラメーターを無視し、すべてのリソースのリストを返します。ユーザーが慎重でない場合、ユーザーは呼び出しが成功したと考え、リストの最初のリソースを使用します。

一方、単数形を使用する場合：

GET /resource?Id=123

Idが正しい方法で指定されていないため、サーバーはエラーを返す可能性が高く、ユーザーは何かが間違っていることを認識しなければなりません。