REST APIの命名規則のガイドラインはありますか?[閉まっている]


212

REST APIを作成する場合、API内の命名規則に関するガイドラインやデファクトスタンダード(例:URLエンドポイントパスコンポーネント、クエリ文字列パラメーター)はありますか?キャメルキャップは標準またはアンダースコアですか?他?

例えば:

api.service.com/helloWorld/userId/x

または

api.service.com/hello_world/user_id/x

注:これはRESTful API設計の問題ではなく、使用される最終的なパスコンポーネントやクエリ文字列パラメーターに使用する命名規則のガイドラインです。

任意のガイドラインをいただければ幸いです。

回答:


150

キャメルキャップは避けるべきだと思います。通常は小文字を使用します。下線も避け、代わりにダッシュを使用します

したがって、URLは次のようになります(要求された設計の問題は無視されます:-))。

api.service.com/hello-world/user-id/x

187
RFC2616によると、URLのスキームとホストの部分のみが大文字と小文字を区別しません。URLの残りの部分、つまりパスとクエリでは大文字と小文字を区別する必要があります。w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3
Darrel Miller

10
ダニエル、あなたは正しい、それを指摘してくれてありがとう。ただし、事実上、通常はURLで大文字と小文字の区別、特にリソース名の部分が無視されることが予想されます。useridとuseridが異なる動作をすることは意味がありません(それらの1つが404を返さない限り)
LiorH

18
@LiorH:なぜ大文字と小文字を区別しても「意味がない」と思いますか?他の多くのコンテキストでは、大文字と小文字が区別されて良い効果が得られます。URLエンドポイントの大文字と小文字を区別するいくつかのWebサービス(Amazon S3など)があり、それは非常に適切だと思います。
ハンク

6
@Dennis Windowsサーバーのファイルシステムは、私がひどく間違っているのでない限り、デフォルトで大文字と小文字を区別しませんtechnet.microsoft.com/en-us/library/cc725747.aspx
samspot

5
@samspotいいね!Windowsは、サーバーを作成するときに、大文字と小文字を区別するファイル名に直接なったと思いました。すごい、彼らはできる限り彼らの道を押し続けていた、すなわち「1 MicroSoft Way」。;-)
デニス

87

DropboxTwitterGoogle Web ServicesFacebookのREST APIはすべてアンダースコアを使用します。


24
その副作用の1つは、下線が引かれた「単語」が全体としてGoogleの検索インデックスに保持されることです。ハイヘンになったものは、別々の単語に分割されます。
Dennis


11
Google Maps APIではアンダースコアが使用されますが、Googleスタイルガイドではキャメルケースが必要です。Google +のAPIカスタム検索API、他の人の間で、使用キャメルケース。
ベンジャミン

2
しかし、彼らはまだ使用「 - 」区切り文字としてそれらのURLを:P developers.google.com/custom-search/json-api/v1/reference/cse/... developers.google.com/+/best-practices dev.twitter。 com / overview / case-studies 一方、クエリパラメータでcamelCaseを使用します。
Mattias

1
誰も知らない...
ピョートルクラ

84

通常のWebリソースのURIをよく見てください。それらはあなたのテンプレートです。ディレクトリツリーについて考えてください。Linuxに似た単純なファイル名とディレクトリ名を使用します。

HelloWorld本当に良いクラスのリソースではありません。「もの」ではないようです。そうかもしれませんが、それはあまり名詞のようではありません。A greetingは物です。

user-idあなたが取得している名詞かもしれません。ただし、リクエストの結果がuser_idのみであることは疑わしいです。リクエストの結果がユーザーである可能性がはるかに高くなります。したがって、user取得する名詞は

www.example.com/greeting/user/x/

私には理にかなっています。RESTリクエストを一種の名詞句、つまり階層(または分類法、またはディレクトリ)を通るパスにすることに焦点を当てます。可能な限り最も単純な名詞を使用し、可能であれば名詞句を避けます。

通常、複合名詞句は通常、階層内の別のステップを意味します。だから、持っていない/hello-world/user//hello-universe/user/。とが/hello/world/user/ありhello/universe/user/ます。または多分/world/hello/user/そして/universe/hello/user/

ポイントは、リソース間のナビゲーションパスを提供することです。


4
私の質問は、最終的なパス名やクエリ文字列パラメータの命名規則に関するものです。設計上の推奨事項に同意しますので、よろしくお願いしますが、この質問では、命名規則についてお伺いします。
jnorris 2009

1
ただ注意してください。非階層リソースにRESTを使用することを妨げるものは何もありません。使用する実際のURI命名規則は重要ではありません。見栄えがよく、サーバーで簡単に解析できるものを使用してください。応答のハイパーテキストを介してURIをリソースに送信する必要があるため、クライアントはURIの生成について何も知らないはずです。
aehlke 2009

30

「UserId」は完全に間違ったアプローチです。動詞(HTTPメソッド)と名詞のアプローチは、Roy FieldingがRESTアーキテクチャに意味したものです。名詞は次のいずれかです。

  1. コレクション物事の

良い命名規則の1つは次のとおりです。

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

{media_type}は、json、xml、rss、pdf、png、htmlのいずれかです。

次のように、末尾に「s」を追加することで、コレクションを区別できます。

'users.json' *collection of things*
'user/id_value.json' *single thing*

ただし、これは、「s」を配置した場所と配置しなかった場所を追跡する必要があることを意味します。さらに、惑星の半分(初心者向けのアジア人)は複数形を明示せずに言語を話すため、URLはあまり友好的ではありません。


{var}の意味は?たとえば... / user / username / tomsawyerのような名前でユーザーを検索すると、
Hans-PeterStörr2012年

1
x、y、zという名前の3つの変数(var)がある場合、URLは次のようになります。sub.domain.tld/ x / value_of_x / y / value_of_y / z / value_of_z
Dennis

@hstoerr念のために言っておきますが、ほとんどのスクリプト言語では、ある種の「中括弧変数置換」を使用しています。したがって、{var}は何らかの変数(その名前)がそこに存在することを意味します。したがって、次の{value}はその前の{var}の値です。例:sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_averages_higher_than/4.json]は、yelp.comからjsonの結果を取得して、食品のレビューを表示しようとしています4より大きい値
Dennis

これは、私の考えと国際的に考えるための賞賛における最良の答えです。
beiller 14

14

いいえ。RESTはURIの命名規則とは関係ありません。これらの規則をハイパーテキスト経由ではなく、アウトオブバンドでAPIの一部として含める場合、APIはRESTfulではありません。

詳細については、http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-drivenを参照してください


44
少し休憩してください...見栄えの良いURLを用意しておくのもいいことです。
HDave

1
@HDaveに同意します。簡単に理解できるURLを用意することは、RESTの精神に非常に忠実です。あなたはURLを扱っていますが、コード内の変数やパラメータの名前と同じくらい簡単に理解してほしくないのですか?
mahemoff 2012

4
@mahemoff申し訳ありませんが、これは私が非常に知識を深めていることです。しかし、URLがどのように見えるかは、RESTとは関係ありません。これは、それらが良いものではないという意味ではなく、RESTが説明するものと直交しているだけです。読みやすく構造化されたURLがあるという理由だけでRPC APIをRESTとして説明することにつながるので、RESTはURLをこのように構造化することについてであると言うのは誤解を招きます。
aehlke

5
要約すると、見栄えの良いURLは素晴らしいものであり、誰もがそれらを持つ必要があります。RESTとは関係ありません。
aehlke

1
@aehlkeこれを片付けてくれてありがとう。残りはURL構造についてではありません。なぜ人には理解が難しいのか分かりません。
user1431072 2014

9

ドメイン名では大文字と小文字が区別されませんが、URIの残りの部分では大文字と小文字が区別されます。URIで大文字と小文字が区別されないと想定することは大きな間違いです。



2

その例ではラクダの問題が問題だとは思わないが、上の例のRESTfulな命名規則は次のようになると思います。

api.service.com/helloWorld/userId/x

むしろuserIdをクエリパラメータにする(これは完全に合法です)私の例では、IMOのリソースをよりRESTfulな方法で示しています。


これはRESTful API設計の問題ではなく、使用される最終的なパスコンポーネントやクエリ文字列パラメーターに使用する命名規則のガイドラインの問題です。あなたの例では、パスコンポーネントはあなたが使ったようにキャメルキャップに入れるべきですか、それともアンダースコアに入れるべきですか?
jnorris 2009

まあ、RESTではあなたのURLはあなたのインターフェースなので、それは一種のAPIの質問です。私はあなたの例に固有のガイドラインはないと思いますが、私はキャメルケースを個人的に使います。
ガンダルフ

HTTPスタックのどのレベルでもキャッシュしたいリソースには、クエリパラメータを使用しないでください。
aehlke 2009

@aehlke正反対のことが当てはまります。クエリパラメータをキャッシュしたくない場合は、パラメータのGETスタイルを使用します。〜OR〜DARN SUREを作成して、キャッシュしたくないもののアンチキャッシュヘッダーを変更/挿入します。また、オブジェクト/ページのreturendのハッシュであるいくつかのヘッダーがあります。それを使用して、キャッシュしたいものの変更を示しますが、編集時に更新されます。
デニス

@aehlkeキャッシングについて知り、それを追加しています。スピードアップの1つがこれらすべてのヘッダーを実行し、コンテンツが変更されたときにファイル名とファイルへのすべての参照を変更して、長いキャッシュ時間が経過した後にブラウザーとプロキシーが新しいバージョンをサーバーに提供するCodeCampプレゼンテーションを覚えていますセットする。詳細は次のとおりです
Dennis

2

Oauth2でクライアントを認証する場合、少なくとも2つのパラメーター名にアンダースコアが必要になると思います。

  • クライアントID
  • client_secret

(まだ公開されていない)REST APIでcamelCaseを使用しました。APIドキュメントを書いている間、私はすべてをsnake_caseに変更することを考えていました。そのため、他のパラメーターではないのにOauthパラメーターがsnake_caseである理由を説明する必要はありません。

参照:https : //tools.ietf.org/html/rfc6749


0

REST URLではできるだけ少ない特殊文字を使用することが望ましいと思います。RESTの利点の1つは、サービスの「インターフェース」を読みやすくすることです。キャメルケースまたはパスカルケースは、リソース名(ユーザーまたはユーザー)に適しています。RESTに関するハードスタンダードは本当にないと思います。

また、Gandalfは正しいと思います。通常、RESTではクエリ文字列パラメーターを使用せず、処理するリソースを定義するパスを作成する方がクリーンです。

http://api.example.com/HelloWorld/Users/12345/Order/3/etc

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.