URL Construction    (61K)

REST is based around a hyperlinking model. You start at a document, and use links on that document to find the next. These links are Uniform Resource Locators (URLs), and contain useful structure. So when is it OK to look at that structure and try to interpret it? When is it OK to guess at what other URLs might exist from the set you can actually see?    (611)

Principles    (612)

Two REST principles come into play in this decision, and at first they seem to be in conflict. REST proponents will often argue both that    (613)

There are obviously some other useful principles, most of which can be found here.    (616)

The second principle in my list is what stops us from using urls like <http://example.com/172b6a8a-b87b-40e3-b258-3e658f085578>. A URL like this isn't easy to remember, type in, navigate, or manage. In REST (as on the web), we would prefer a URL like this one: <http://example.com/2006/08/01/UrlConstruction>.    (617)

The guide as to what information should be included comes down to what information forms that document's identity. It can be useful to include a date whenever a document is written or released, never to be changed. If it were ever to be updated or re-released, it would deserve a new URL for the new version. On the other hand, you may have a separate url for the latest version or for the list of available versions. That is a separate resource from the resources of any particular version.    (618)

Muddying of the Waters    (619)

So the information is there. Noone is pretending it isn't there. Why can't we use it in our applications?    (61A)

In REST, we have the RestTriangle. Nouns name things. Verbs dictate how information moves between client and resource. Content represents the transfered information (state). While each performs its individual role we can attack each problem separately. Defining these different aspects of our global information system is a social process. Whenever we allow cross-over between the corners of the triangle we muddy the waters for anyone trying to solve any of the particular social problem domains and convey information. Should it go into the URI, or into the content? The answer is sometimes "both, but the client only reads it from your content".    (61B)

Coupling Effects    (61C)

When the URI is opened up as a channel for information transfer, the structure of the URL must be agreed between client and server. If URI construction is employed, not only must the structure of a single URL be agreed, but whole sub-trees of the server's URI-space.    (61D)

If a client that is doing URI construction moves over to a similar service offered by another supplier, it will take its URI-space assumptions with it. This causes the new supplier to be bound into the same agreement as existed between the original client and service provider.    (61E)

These kinds of coupling effects are normal and expected in the content-type space. We expect that google and yahoo are both going to have to agree on subsets of what their HTML tags mean if clients are going to usefully access their services. URI-space coupling takes things a level beyond that. When both URI-space and content type are coupled, service providers are limited in how they can design and deploy their services. Even the same service over time may need to refactor its URI-space, but be constrained to the model it has agreed with clients.    (61F)

The URI space is meant to be able to evolve to support scalability. In theory, even non-overlapping resource should be able to be served from a different machine or cluster. This fine-grain control can be compromised by clients who know without being told where to find particular resources, or assume a particular path structure in order to extract relevant data.    (61G)

Conclusion    (61H)

As a human user, feel free to seek out new resource you guess may exist. Once you have confirmed they exist, feel free to put them into the configuration file of an automation for later query and retrieval.    (61I)

If you are an automation you should take your configuration as your starting set of URLs. From there you can crawl, or fill out server-provided forms to locate resources. Don't guess at the existence of resources, and don't assume that just because you can parse and understand a URL today means you will also be able to parse and understand tomorrow's URL.    (61J)