URL-centric web application design

09 January 2012

Peter Hilton

by Peter Hilton

One good way to start building a web application is to plan its HTTP interface - its URLs. This URL-centric design is an alternative to a data model-centric design that starts with the application’s data, or a UI-centric design that is based on how users will interact with the application’s user-interface. URL-centric design is a kind of API design.

URL-centric design

URL-centric design means identifying your application’s resources, and operations on those resources, and creating a series of URLs that provide HTTP access to those resources and operations. Once you have a solid URL design, you can add a user-interface layer on top of this HTTP interface, and add a model that backs the HTTP resources.

For example, suppose we are designing a web based product catalogue. We start by identifying a ‘product details’ resource - information about a product, as well as links to related operations. Two related operations such as ‘get product details’ and ‘add comment to product details’.

GET /product/5010255079763
POST /product/5010255079763/comments

This kind of resource is typically more coarse-grained than the entities in a data model: ‘product details’ may span multiple database tables. Similarly, the operations are higher level than the CRUD operations that we tend to think of, for database records.

The architect

Whether you are inclined to adopt this approach to application design depends on your background. In the past, enterprise application development has focused more on data models, while consumer software is often more user-interfaction oriented. However, the relatively recent trends towards service-oriented architecture and REST architecture have encouraged more application architects to think in terms of APIs.

URL-centric design only starts to seem like an obvious approach when you think of ‘the web’ as the pervasive ecosystem where software runs, whether it is the public Internet World-Wide Web or a corporate intranet. If you imagine that it would be useful for web-based stuff (both applications and documents) to be able to link to each others pages (HTTP resources), then you inevitably realise that it will help if their URLs are designed and perhaps even predictable, rather than random.


The idea that applications might link to each other naturally leads to the idea to APIs that let you implement more interesting operations than merely directing a reader to another web page. This is the key benefit of URL-centric design: that you can create a consistent public API for your application that is more stable than either the physical data model represented by its model classes, or the user-interface generated by its view templates.

This is especially useful if the HTTP API is the basis for more than one external interface. For example, your application might have a plain HTML user-interface, a JavaScript-based user-interface that uses Ajax to access the server’s HTTP interface, as well as arbitrary HTTP clients that use your HTTP API directly.


This is an API-centric perspective on your application in which you consider that HTTP requests will not necessarily come from your own application’s web-based user-interface. In particular, this is the most natural approach if you are designing a REST-style HTTP API, as described in chapter 5 - ‘Designing Read-Only Resource-Oriented Services’ - of the book RESTful Web Services (highly recommended). This describes a detailed procedure that can be summarised as follows.

  1. Identify resources.

  2. Name each resource with a URI.

  3. Expose each resource using a subset of HTTP’s uniform interface (HTTP methods).

  4. Design resource representations to send over HTTP, typically HTML, XML or JSON.

  5. Use hyperlinks and forms to connect resources to each other.

You can apply this approach to an application whose only external interface is a web-based (HTML) user-interface, since URL-centric design is really just part of REST architectural design. In the case of a simple web application, with no external API, the only difference to the general case is that the representations that the server sends to the client are HTML documents, and the representations that the client sends to the server are encoded HTML form data.


URL-centric design offers benefits when used in addition to a more traditional approach based on the data model, and the more recent trend towards starting with the user-interface. Designing your application’s URL-based public HTTP interface creates a clean separation between client and server, which can be the basis for supporting multiple client devices, such as a combination of desktop and mobile web interfaces. The same interface can also be the basis of an REST API used in a service-oriented architecture.