The best practices to design URIs for resources

It’s just a book note. The problem to know the best practices to design URIs for resources.

Solution

Use domains and subdomains to logically group or partition resources for localization, distribution, or to enforce various monitoring or security policies.

Use the forward-slash separator(/) in the path portion of the URI to indicate a hierarchical relationship between resources.

Use the comma(,) and semicolon(;) to indicate nonhierarchical elements in the path portion of the URI.

Use the hyphen(-) and underscore(_) characters to improve the readability of names in long path segments.

Use the ampersand(&) to separate parameters in the query portion of the URI.

Avoid including file extensions in URIs.

Domains and subdomains

A logical partition of URIs into domains and subdomains provides several operational benefits for server administration. Make sure to use logical names for subdomains while partitioning URIs. For example, the server could offer localized representations via different subdomains, as in the following:
http://en.example.org/book/1234
http://da.example.org/book/1234
http://fr.example.org/book/1234

Another example is, partition based on the class of clients.
http://www.example.org/book/1234
http://api.example.org/book/1234

In this example, the server offers two subdomains, one for browsers and the other for
custom clients. Such partitioning may let the server allocate different hardware or apply
different routing, monitoring, or security policies for HTML and non-HTML representations.

Forward-slash separator

By convention, the forward slash (/) character is used to convey hierarchical relationships.This is not a hard and fast rule, but most users assume this when they scan URIs. In fact, the forward slash is the only character mentioned in RFC 3986 as typically indicating a hierarchical relationship. For example, all the following URIs convey a hierarchical association between path segments:
http://www.example.org/messages/msg123
http://www.example.org/customer/orders/order1
http://www.example.org/earth/north-america/canada/manitoba

Some web services may use a trailing forward slash for collection resources. Use such conventions with care since some development frameworks may incorrectly remove such slashes or add trailing slashes during URI normalization.

Underscore and hyphen

If you want to make your URIs easy for humans to scan and interpret, use the underscore (_) or hyphen (-) character:
http://www.example.org/blog/this-is-my-first-post
http://www.example.org/my_photos/our_summer_vacation/first_day/setting_up_camp/

Ampersand

Use the ampersand character (&) to separate parameters in the query portion of the URI:
http://www.example.org/print?draftmode&landscape
http://www.example.org/search?word=Antarctica&limit=30

In the first URI shown, the parameters are draft mode and landscape. The second URI has the parameters word=Antarctica and limit=30.

Comma and semicolon

Use the comma (,) and semi-colon (;) characters to indicate nonhierarchical portions of the URI. The semicolon convention is used to identify matrix parameters:
http://www.example.org/co-ordinates;w=39.001409,z=-84.578201
http://www.example.org/axis;x=0,y=9

These characters are valid in the path and query portions of URIs, but not all code libraries recognize the comma and semicolon as separators and may require custom coding to extract these parameters.

Reference

For more information please read the book: Restful Services Cook Book