『REST入門』URIの良い設計

OpenAPI(Swagger) REST

Web上に存在するリソースは、すべてURIで指定することができ、HTTPで操作できます。 そんなURIはクライアントとWebサーバまたはWeb APIを繋ぐ入口となります。 良いURI(クールなURI)を設計することで、変わりにくいURIとなります。

変わりにくいURI

変わりにくいURIと言ったのは、ドメインが変わったり、会社の倒産によるWebサービスの休止が考えられるからです。 このような事態を防ぐことはできませんが、変わりにくいURIを設計することは可能です。

 

URIの設計指針

URIの設計指針として以下が挙げられます。 結論としてURIは名詞で設計します。

・プログラミング言語依存の拡張子を利用しない
・実装依存のパス名を利用しない
・プログラミング言語のメソッド名を利用しない
・セッションIDを含めない
・そのリソースを表現する名詞にする

ログインページのURIを設計する場合は以下のようなシンプルでクールなURIとなります。

https://nikukyulog.com/login

 

URIのユーザビリティ

シンプルなURIは一般ユーザにとって覚えやすく理解しやすいため、ユーザビリティの向上に繋がります。 悪い例

https://nikukyulog.com/servlet/LoginServlet

良い例

https://nikukyulog.com/login

 

URIを変更する場合

URIの変更が必要になった場合は、リダイレクトするべきです。 リダイレクトをすることで古いURIを新しいURIに転送することができます。 リダイレクトはHTTPの仕組みになります。

HTTP/1.1 301 Moved Permanently Location: http://nikukyulog.com/new

  クライアントは「301 Moved Permanently」を受け取るとリダイレクトであることが分かります。 リダイレクトであることから、Locationヘッダに指定されたURIを取得します。

 

URI設計のテクニック

URIの設計のテクニックとして拡張子で表現を指定する方法とマトリックURIについて記載します。

 

拡張子で表現を指定

上記では、拡張子を使うのは設計上良くないと記載しましたが、それは実装に依存する拡張子を使った場合になります。 1つのリソースで複数の表現を持ちたい場合に拡張子を利用することは良いとされます。 例えば、内容が同じ1つのリソースを日本語や英語で表現したい。HTMLやテキスト、JSONで表現したい場合などです。 日本語のリソースの例

https://nikukyulog.com/pet/diary/snow-cone.jp

  英語のリソースの例

https://nikukyulog.com/pet/diary/snow-cone.en

 

マトリクスURI

マトリクスURIは、階層構造を表現するスラッシュ「/」の代わりに、複数のパラメータをセミコロン「;」かカンマ「,」で区切ってリソースを表現します。 例えば地図をリソースとした場合に緯度(Lat)と経度(Lng)で場所を特定するとした場合、マトリクスURIは以下のようになります。 セミコロン「;」で区切る場合

https://nikukyulog.com/map/lat=35.6759323;lng=139.7450316

カンマ「,」で区切る場合

https://nikukyulog.com/map/35.6759323,139.7450316

セミコロンで区切る場合は、パラメータの順序は意味を持ちません。 カンマで区切る場合は、順序が意味を持つ場合に使います。

 

 

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