web-dev-qa-db-ja.com

REST AP​​Iの命名規則のガイドラインはありますか？

REST AP​​Iを作成する場合、API内の命名規則に関するガイドラインまたは事実上の標準はありますか（例：URLエンドポイントパスコンポーネント、クエリ文字列パラメーター）。キャメルキャップは標準ですか、それともアンダースコアですか？他の？

例えば：

api.service.com/helloWorld/userId/x

または

api.service.com/hello_world/user_id/x

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

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

apirestnaming-conventions
197
jnorris

ラクダの帽子は避けるべきだと思います。通常は小文字を使用します。また、アンダースコアを避け、代わりにダッシュを使用します

したがって、URLは次のようになります（要求した設計上の問題は無視してください:-)）

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

Dropbox 、 Twitter 、 Google Web Services および Facebook のREST AP​​Iはすべてアンダースコアを使用します。

81
jz1108

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

HelloWorldは、本当に良いリソースのクラスではありません。 「もの」ではないようです。そうかもしれませんが、あまり名詞に似ていません。 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/。

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

80
S.Lott

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

  1. 物のCollection
  2. A thing

適切な命名規則の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はそれらに優しいものではありません。

29
Dennis

いいえ。RESTはURIの命名規則とは関係ありません。これらの規則をAPIの一部として、ハイパーテキスト経由のみではなく、帯域外で含めると、APIはRESTfulではありません。

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

14
aehlke

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

9
rickoshay

http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html にガイドラインのリストがあります。これはprodで使用しています。ガイドラインは常に議論の余地があります...物事を完璧にすることよりも一貫性の方が重要な場合があります（そのようなことがある場合）。

5
Robert Morschel

その例ではラクダのケースが問題だとは思いませんが、上記の例のよりRESTfulな命名規則は次のようになります。

api.service.com/helloWorld/userId/x

むしろ、userIdをクエリパラメータ（完全に正当なもの）にすると、私の例では、IMOのリソースをよりRESTfulな方法で示しています。

2
Gandalf

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

また、ガンダルフは正しいと思います。通常、RESTではクエリ文字列パラメーターを使用せず、代わりに処理するリソースを定義するパスを作成します。

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

1
Andy White

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

  • クライアントID
  • client_secret

（まだ公開されていない）REST AP​​IでcamelCaseを使用しました。 APIドキュメントの作成中に、すべてをsnake_caseに変更することを考えているので、Oauthパラメーターがsnake_caseであるのに他のパラメーターはそうでない理由を説明する必要はありません。

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

1
Michael