『REST入門』URIの仕様

OpenAPI(Swagger) REST

Web上に存在するリソースは、すべてURIで指定することができ、HTTPで操作できます。
HTTPとURIのシンプルな組み合わせはWebを成功に導いた一因です。ここではURIの仕様について記載します。

URIとは

URIの仕様は「RFC 3986です。

URIの仕様を正しく理解することは、使いやすいWebサービスとWeb APIの第一歩です。

URI(Uniform Resource Identifier)の略で、直訳は「統一リソース識別子」です。

統一とは、すべてが同じルールに従っているということです。

リソースとは、Web上に存在する、ユニークな名前を持ったさまざまな情報。

識別子とは、他のものと区別して指し示すための名前のことです。

つまりURIとは「Web上に存在するさまざまな情報を、決められたルールで、他と区別して指し示す名前」のことです。

URIを使うことでWeb上に存在するすべてのリソースを一意に示せます。

つまりURIさえあれば、すべてのリソースに簡単にアクセスできます。

 

URIで使用できる文字

次の文字がURIのパスに使えます。

アルファベット A-Za-z
数字 0-9
記号 -.~:@!$&'()

上記は、ASCII文字になります。

URIには日本語を直接使うことができません。

%エンコーディングという方式を使うことで、ASCII以外の日本語などの文字をURIに使うことができます。

 

%エンコーディング(URLはたはURIエンコーディング)

URIの仕様で許可された文字以外を使う場合に%エンコーディングでエンコードします。

UTF-8の「あ」を%エンコーディングした場合は、3バイトの「%E3%81%82」にエンコードします。文字エンコーディングによって、%エンコード結果は異なります。

以下サイトで各文字コーディングを%エンコーディングでエンコードできます。

 

URIの最大長

URIの仕様では長さに制限はありません。

しかし、ブラウザで制限があり、IEの場合は2,083バイトまでとなります。

そのため事実上この長さで実装することになります。

 

URIスキーム

URIスキームとは、インターネット上のリソースの所在を表すURIの先頭部分で、リソースに到達するための手段(プロトコル)を表したものです。

URIスキームはIANA(アイアナ)の公式サイトで公開されています。

 

URIの構文

以下に単純なURIの例を見てみましょう。

こちらはよく目にするURIになるかと思います。

https://nikukyulog.com/programming/rest/architecture-style/


このURIを構成するパーツは次のようになっています。

[URIスキーム]://[ホスト名]/[パス]

URIスキーム https
ホスト名 nikukyulog.com
パス /programming/rest/architecture-style/

URIスキーム、ホスト名、パスについては以下の複雑なURIで解説します。

もう少し複雑なURIを見てみたいと思います。以下のURIは例になります。

https://rokka:pass@nikukyulog.com:8000/search?q=test&debug=true#2


このURIを構成するパーツは次のようになっています。

[URIスキーム]://[ユーザ情報]@[ホスト名]:[ポート番号]/[パス]?[クエリパラメータ]#[URIフラグメント]

URIスキーム http
ユーザ情報 rokka:pass
ホスト名 nikukyulog.com
ポート番号 8000
パス /search
クエリパラメータ ?q=test&debug=true
URIフラグメント #2

URIスキームは、利用するプロトコルを指します。

URIスキームの後の「:」はURIスキームとその後ろの区切りで、「//」はユーザ情報とホスト名の開始を告げる文字列です。

ユーザ情報は、このリソースにアクセスする際のユーザ名とパスワードになります。

ユーザ名とパスワードは「:」で区切ります。

ユーザ情報の区切り文字が「@」になります。

ホスト名は、DNS(Domain Name System)で名前が解決できるドメイン名かIPアドレスで、インターネット上で一意になります。

ポート番号は、ホストにアクセスするときのプロトコルで用いるTCPのポート番号になります。

ポート番号は省略でき、省略した場合はそのプロトコルのデフォルトの値が使われます。HTTPのデフォルト値は80番、HTTPSは443番になります。

ホスト名とポート番号は「:」で区切ります。

パスは、階層を表すパスになります。パスは、ホストの中でリソースをを一意に指し示します。

クエリパラメータは、「?」で区切り、名前=値形式のクエリが続きます。

上記の例では「q=test」と「debug=true」の2つがクエリにまります。

複数クエリがある場合は「&」で連結します。

クエリパラメータは、検索サービスに検索キーワードを渡すときなど、クライアントから動的にURIを生成するときに利用します。

URIフラグメントは、「#」で始まり、「#」前までで表現されたURIが指し示すリソース内部の、さらに細かい部分を特定するときに利用します。

上記のようなホスト名パスの付け方によって、世界中のリソースのURIと絶対に重複しないよになっているのです。

 

絶対URIと相対URI

URIには絶対URI相対URIがあります。相対URIはURIスキームやホスト名を省いて、パスだけで表現します。

 絶対URI

https://nikukyulog.com/foo/ber


 相対URI

/foo/ber


URIのパスは、「/」をルートとして、ディレクトリ名を「/」で区切り、必要であれば最後にファイル名を接続する記法になります。

OSのファイルシステムでは、ルートから記述したパスのことを絶対パスと呼びます。

OSのファイルシステムの場合、毎回絶対パスを書くのは冗長なので、カレントディレクトリ(現在いる場所)から記述したパスのことを相対パスと呼び、カレントディレクトリは「.」、カレントディレクトリの親ディレクトリを「..」で表現します。

 

URIの構文(ベースURI)

相対URIは、起点となるURIがどこなのかが分からないとクライアントでは解釈できません。この起点となるURIを指定するのがベースURI(基底URI)です。

ベースURIを指定する方法として、HTMLやXMLの中で明示的にベースURIを指定する方法があります。

HTMLの場合は<head>要素の中に<base>要素を入れます。

XMLの場合はxml:base属性を利用することで、どの要素でもベースURIを指定できます。
ここでは、XMLの場合を例に記載します。

 

相対RUIには、相対パスと同様に「.」、「..」が使えます。また、/」から始まる相対パスはホスト名に続くパスとして解釈します。

以下に「https://nikukyulog.com/foo/bar」をベースURIとした場合に、相対URIからどのような絶対URIに変換されるかを表にまとめました。

相対パスから絶対パスへの変換(ベースURIは、https://nikukyulog.com/foo/bar)

相対URI 絶対URI
hoge https://nikukyulog.com/foo/bar/hoge
hoge/fuga https://nikukyulog.com/foo/ber/hoge/fuga
./hoge https://nikukyulog.com/foo/bar/hoge
../hoge https://nikukyulog.com/foo/hoge
../hoge/fuga https://nikukyulog.comfoo/foo/hoge/fuga
/hoge/fuga https://nikukyulog.com/foo/hoge/fuga
../../hoge https://nikukyulog.com/hoge
?q=hoge https://nikukyulog.com/foo/ber?q=hoge
#hoge https://nikukyulog.com/foo/ber#hoge

 

URIの実装で気を付けること

WebサービスやWeb APIを実装する上でURIの仕様上気を付けるところは、相対URIと%エンコードの扱いです。

クライアント側で相対URIを解決するのは手間がかかるので、なるべく絶対URIを使うほうが親切です。

URIにASCII文字以外を使う場合は、文字エンコーディングの混乱を避けるため、なるべくUTF-8を用いることが望ましいとされています。

URIとURLとURNの違い

この記事ではURIと書いていますがURLとしても問題ありません。

しかし、正確にはURIはURLとURNを総称する名前になります。

URLには、ドメインを更新しなかったり、サーバが何らかの障害で変更になったりするとアクセスできなくなるという問題があります。

URNは上記の問題を解決するためにドメイン名とは独立してリソースに恒久的なIDを付きます

URIはこのURLとURNの特性を合わせた総称になります。

 

タイトルとURLをコピーしました