Handling resources and URIs
Every document on the World Wide Web (WWW) is represented as a resource in terms of HTTP. This resource is represented as a URI, which is an endpoint that represents a unique resource on a server.
Roy Fielding in his doctoral research states that a URI is known by many names – a WWW address, a Universal Document Identifier (UDI), a URI, a Uniform Resource Locator (URL), and a Uniform Resource Name (URN).
So, what is a URI? A URI is a string (that is, a sequence of characters) that identifies a resource by its location, name, or both (in the WWW world). There are two types of URIs: URLs and URNs.
URLs are widely used and even known to non-developer users. URLs are not only restricted to HTTP but are also used for many other protocols, such as FTP, JDBC, and MAILTO. A URL is an identifier that identifies the network location of a resource. We will go into more detail in the later sections.
The URI syntax
The URI syntax is as follows:
scheme:[//authority]path[?query][#fragment]
As per the syntax, the following is the list of components of a URI:
- Scheme: This refers to a non-empty sequence of characters followed by a colon (
:).schemestarts with a letter and is followed by any combination of digits, letters, periods (.), hyphens (-), or plus characters (+).
Scheme examples include HTTP, HTTPS, MAILTO, FILE, and FTP. URI schemes must be registered with the Internet Assigned Numbers Authority (IANA).
- Authority: This is an optional field and is preceded by
//. It consists of the following optional subfields:- Userinfo: This is a subcomponent that might contain a username and a password, which are both optional.
- Host: This is a subcomponent containing either an IP address or a registered host or domain name.
- Port: This is an optional subcomponent that is followed by a colon (
:).
- Path: A path contains a sequence of segments separated by slash characters (
/). In the preceding GitHub REST API example,/licensesis the path. - Query: This is an optional component and is preceded by a question mark (
?). The query component contains a query string of non-hierarchical data. Each parameter is separated by an ampersand (&) in the query component and parameter values are assigned using an equals (=) operator. - Fragment: This is an optional field and is preceded by a hash (
#). The fragment component includes a fragment identifier that gives direction to a secondary resource.
The following list contains examples of URIs:
- www.packt.com: This doesn’t contain the scheme. It just contains the domain name. There is no port either, which means it points to the default port.
index.html: This contains no scheme nor authority. It only contains the path.- https://www.packt.com/index.html: This contains the scheme, authority, and path.
Here are some examples of different scheme URIs:
- mailto:[email protected]
- telnet://192.168.0.1:23/
- ldap://[2020:ab9::9]/c=AB?objectClass?obj
Note
From a REST perspective, the path component of a URI is very important because it represents the resource path and your API endpoint paths are formed based on it. For example, take a look at the following:
GET https://www.domain.com/api/v1/order/1
Here, /api/v1/order/1 represents the path and GET represents the HTTP method.
What is a URL?
If you look closely, most of the URI examples mentioned earlier can also be called URLs. A URI is an identifier; on the other hand, a URL is not only an identifier, but it also tells you how to get to it.
Request for Comments (RFC)
As per RFC-3986 on URIs (https://datatracker.ietf.org/doc/html/rfc3986), the term URL refers to the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism (for example, its network location).
A URL represents the full web address of a resource, including the protocol name (the scheme), the hostname port (in case the HTTP port is not 80; for HTTPS, the default port is 443), part of the authority component, the path, and optional query and fragment subcomponents.
What is a URN?
URNs are not commonly used. They are also a type of URI that starts with a scheme – urn. The following URN example is directly taken from RFC-3986 for URIs (https://www.ietf.org/rfc/rfc3986.txt):
urn:oasis:names:specification:docbook:dtd:xml:4.1.2
This example follows the "urn:" <NID> ":" <NSS> syntax, where <NID> is the namespace identifier, and <NSS> is the namespace-specific string. We are not going to use URNs in our REST implementation. However, you can read more about them at RFC-2141 (https://tools.ietf.org/html/rfc2141).
Note
As per RFC-3986 on URIs (https://datatracker.ietf.org/doc/html/rfc3986), the term URN has been used historically to refer to both URIs under the “urn” scheme RFC-2141, which are required to remain globally unique and persistent even when the resource ceases to exist or becomes unavailable, and to any other URI with the properties of a name.
Now that you understand the difference between a URI and a URN and how they make up URIs, let’s learn about the second concept that makes up REST: HTTP methods and status codes.
