REST API URIの7つの規則
REST API URIのルールについて学ぶ前に、用語を簡単に絞り込んで進めましょう。
URI
REST API は URL を使用します。今日のウェブでは、URIデザインは、APIのリソースモデルを明確に伝える傑作から、人々が理解するのが難しいものまでさまざまです。
Tim Burners Leeは、「Webアーキテクチャの原則」というリストにURIの不透明性に関するメモを記載しました。
「識別子を使用できる唯一のことは、オブジェクトを参照することです。逆参照しない場合は、他の情報を取得するにはURI文字列の内容を参照してください。」
クライアントはWebの接続パラダイムに従う必要があり、URIを不完全な識別子として扱う必要があります。
REST APIデザイナーは、REST APのリソースモデルを潜在的なクライアント開発者に渡すURIを作成する必要があります。
この投稿では、 REST API URIのいくつかのデザインルールを紹介します。
ルールについて学ぶ前に、このセクションで説明するルールに応じて、URI形式の単語はURI形式に関連しています。 RFC 3986は、以下のように一般的なURI構文を定義しました。
URI = scheme "://" authority "/" path ["?" query ] [ "#" fragment ]
ルール1
末尾のスラッシュ（/）はURIに含まれてはいけません。
これは、URIパスを決定する最後の文字として必ず従うべき重要な規則の1つです。スラッシュは意味がまったくないだけでなく、混乱を引き起こす可能性があります。REST APIでは、クライアント開発者に渡されるAPI URLに末尾のスラッシュを含めないでください。
多くのWebコンポーネントまたはフレームワークは、次の2つのURIを同じように扱います。
http://moretranslate.co.kr/moretranslate
http://moretranslate.co.kr/moretranslate/
ただし、URI内のすべての文字はリソースの一意のIDに含まれています。
2つの異なるURIは他の2つのリソースにマップされます。URIが異なる場合、リソースも異なります。したがって、REST APIはクリーンで明確なURIを生成して渡す必要があります。また、クライアントが不正確にアクセスしようとするすべての試みを受け入れてはいけません。
私たちの開発パートナーであるクライアントだけがAPI呼び出しの対象ではないからです。
ルール2
階層関係を表すときは、スラッシュ区切り文字（/）を使用する必要があります。
スラッシュ文字は、URIのパス部分のリソース間の階層関係を表すために使用されます。
例： http: //board.com/board/52 ->掲示板の52番の記事。
ルール3
URIの可読性を高めるためにハイフン（-）文字を使用する
あなたが定義したURIが人々に読みやすくなるように、ハイフン文字を使用してください。英語でスペースやハイフンを使用するすべての場所で、URIにハイフンを使用する必要があります。
URIを人が簡単にスキャンして解釈できるように、ハイフン（ - ）文字を使用して長いパスセグメントの名前の読みやすさを向上させます。英語でスペースやハイフンを使用するすべての場所で、URIにハイフンを使用する必要があります。
例: http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post
ルール4
アンダーバー（_）文字はURIには使用されません
テキストビューアプログラム（ブラウザ、エディタなど）は、クリックできることを表すためにURIを下線にします。プログラムのフォントによっては、アンダーバー（_）文字がこれらの下線のために部分的に隠れたり完全に隠れたりすることがあります。
この混乱を避けるために、アンダースコア（_）の代わりにハイフン（ - ）文字を使用することをお勧めします。
ルール5
URIの作成には小文字が適しています
大文字が原因で問題が発生することがあるため、URIを作成するときは小文字を使用することをお勧めします。RFC 3986は、スキームとホストコンポーネントを除いてURIを大文字と小文字を区別して定義します。大文字で問題が発生する可能性があるため、便利な場合はURIパスに小文字を使用することをお勧めします。
例:
1) http://api.example.com/my-folder/my-doc
2) HTTP://API.EXAMPLE.COM/my-folder/my-doc
上記のURIは大丈夫です。URIフォーマット仕様（RFC 3986）は、このURIをURI＃1と同じと見なします。
3) http://api.example.com/My-Folder/my-doc
この URI は URI 1 と 2 と同じではないため、不要な混乱を引き起こす可能性があります。
ルール6
ファイル拡張子はURIに含まれていません
Web上のドット（.）は、URIのファイル名と拡張子を区別するために使用されます。REST APIは、メッセージエンティティ本体の本文形式を表すために、これらのファイル拡張子をURIに含めないでください。代わりに、Content-Typeというヘッダーを介して渡されるように、メディアタイプを使用して本文のコンテンツを処理する方法を決定する必要があります。
http://api.college.com/students/3248234/courses/2005/fall.json
http://api.college.com/students/3248234/courses/2005/fall
形式を表現するためにファイル拡張子を使用しないでください。
REST APIクライアントは、HTTPが提供するフォーマット選択メカニズムであるAcceptリクエストヘッダを使用することをお勧めします。
簡単なリンクとデバッグを可能にするために、REST APIはクエリ文字列パラメータを介してメディアタイプの選択をサポートできます。
ルール7
通常、URIは英語で書かれていますが、書かれる英語は単数でなければなりませんか？復讐でなければなりませんか？
これには単純な保持ルールが適用されます。単一のインスタンスを複数形で表示するのは間違っていると思うかもしれませんが、URIの型を複数形として使用することが実務でよく使われています。これには単純な保持ルールが適用されます。内部文法学者は、複数形を使用してリソースの単一インスタンスを記述するのは間違っていると言うでしょうが、実用的な答えはURI形式を一貫して維持し、常に複数形を使用することです。
奇妙な複数形（person / peopleなど）を扱わなくても、APIコンシューマが使いやすく、APIプロバイダが実装するのが簡単です。 ）の形で処理された
しかし、関係はどのように扱いますか？関係が他のリソース内にのみ存在できる場合、RESTFULの原則は有用なガイダンスを提供します。たとえば、ある生徒に複数のコースがあります。これらのプロセスは、次のように/ studentsにマップされます。
http://api.college.com/students/3248234/courses ID 3248234の学生が学習したすべてのコースのリストを検索する
http://api.college.com/students/3248234/courses/physics IDが3248234の学生のためのコース物理学を検索してください。
結論
REST API サービスを 設計するときは、URIで定義されているリソースに注意を払う必要があります。
サービスの各リソースは、少なくとも1つのURIで識別されます。特定のURIがリソースを適切に説明するときに最適です。URIは、理解性と使いやすさを向上させるために予測可能でなければならず、階層的でなければなりません。つまり、一貫性があるという観点から予測可能であり、データが構造を備えているという点で階層的であるということです。
RESTFul APIは消費者向けに書かれています。URIの名前と構造は、その消費者に意味を伝えることができるはずです。上記のルールによれば、はるかに幸せなクライアントで、はるかにクリーンなREST APIを作成できます。これは必ずしも守らなければならない制約ではありません。ただし、上記の規則に従うことでAPIを向上させることができます。
*本文内容は https://dzone.com/articles/7-rules-for-rest-api-uri-design-1 を脚色した資料です。
7 Rules for REST API URI Design - DZone Integration
URIs, or Uniform Resource Identifiers, should be designed to be readable and clearly communicate the API resource model. These rules will help you succeed.
dzone.com
댓글
댓글 쓰기