RESTful Web Services Cookbook

Chapter 4. Designing URIs

URIs are identifiers of resources that work across the Web. A URI consists of a scheme (such as http and https), a host (such as www.example.org), a port number followed by a path with one or more segments (such as /users/1234), and a query string. In this chapter, our focus is on designing URIs for RESTful web services:

Recipe 4.1

Use this recipe to learn some commonly practiced URI design conventions.

Recipe 4.2

Use this recipe to learn some dos and don’ts to keep URIs as opaque identifiers.

Recipe 4.3

Treating URIs as opaque identifiers helps decouple clients from servers. This recipe shows techniques that the server can employ to help clients treat URIs as opaque.

Recipe 4.4

Since URIs are a key part of the interface between clients and servers, it is important to keep them “cool,” i.e., stable and permanent. Use this recipe to learn some practices to help keep URIs cool.

4.1. How to Design URIs

URIs are opaque resource identifiers. In most cases, clients need not be concerned with how a server designs its URIs. However, following common conventions when designing URIs has several advantages:

• URIs that support convention are usually easy to debug and manage.

• Servers can centralize code to extract data from request URIs.

• You can avoid spending valuable design and implementation time inventing new conventions and rules for processing URIs.

• Partitioning the server’s URIs across domains, subdomains, and paths gives you operational flexibility for load distribution, monitoring, ...