URI vs URL in REST: Key Differences and Usage Explained

In REST, a URI (Uniform Resource Identifier) is a string that identifies a resource either by location, name, or both, while a URL (Uniform Resource Locator) is a specific type of URI that provides the means to locate the resource on the internet. Simply put, all URLs are URIs, but not all URIs are URLs.

Quick Comparison

Here is a quick table to compare URI and URL based on key factors:

Factor	URI	URL
Definition	A string that identifies a resource by name, location, or both	A string that identifies a resource by its location on the internet
Scope	Broader concept including URLs and URNs	A subset of URI focused on location
Example	urn:isbn:0451450523	https://example.com/resource
Purpose	Identify any resource uniquely	Locate and access a resource
Usage in REST	Used to identify resources	Used to specify resource addresses
Contains Protocol	May or may not include protocol	Always includes protocol like http or https

Key Differences

A URI is a generic term for all types of resource identifiers. It can be a URL, which tells you where to find the resource, or a URN (Uniform Resource Name), which names the resource without giving its location. For example, urn:isbn:0451450523 is a URI but not a URL.

A URL is a specific kind of URI that provides the exact address to access a resource on the internet, including the protocol (like http or https), domain, and path. For example, https://api.example.com/users/123 is a URL and also a URI.

In REST APIs, the term URI is often used to mean the resource identifier, which can be a URL. However, technically, a URL is a URI that includes the location details needed to retrieve the resource. This distinction helps understand that REST resources are identified by URIs, and URLs are the common way to locate them.

URI Example in REST

This example shows a URI identifying a resource in a REST API:

http

GET /users/123 HTTP/1.1
Host: api.example.com

Output

Request to get user with ID 123

URL Equivalent in REST

This example shows the full URL used to access the same resource:

plaintext

https://api.example.com/users/123

Output

URL to access user with ID 123

When to Use Which

Choose URI when you want to talk about resource identification in a general sense, including names and locations. Use URL when you specifically mean the web address that locates and accesses the resource. In REST, URLs are the practical form of URIs used to call APIs, but understanding the URI concept helps in designing and documenting APIs clearly.

Key Takeaways

A URI identifies a resource by name, location, or both, while a URL specifically locates a resource on the internet.

All URLs are URIs, but not all URIs are URLs.

In REST, URIs identify resources; URLs are the common way to access them.

Use URL when you need the full address including protocol to reach a resource.

Understanding URI vs URL helps design clearer REST APIs and documentation.