Avoiding a fixed resource

Question

Roy fielding writes

The REST API should not define fixed resource names or hierarchies (the obvious client-server relationship). Servers must have the freedom to manage their own namespace. Instead, allow the servers to instruct clients on how to build the appropriate URIs, for example, in HTML forms and URI templates, by defining these instructions inside media types and links.

How do you do this for intersystem interfaces? Suppose a client wants to create an order on the server http://my.server.org. It is assumed that to create an order he should use the url http://my.server.org/newOrder , and not http: //my.server .org / nO or something else?

For the human interface (i.e. the browser), I assume that the server will provide some form of link (possibly in the form element), and the text around and in this link will tell the user which form on this page is correct for creating an order ( as intended to create a user or go to some search result)

What is the mechanics used for client side implementation? And also: are they really used or are most people just linking the URLs to the client?

Answer 1

How do you do this for intersystem interfaces? Tell the client he wants to create an order on the server http://my.server.org he must find out that it is supposed to use the URL http://my.server.org/newOrder to create in the order, and not http: // my .server.org / nO or anything else?

He does not study. Machine clients, as a rule, cannot "learn". Not yet, at least we're still up to Skynet. You must "teach" them.

But what’s the key is that you don’t learn their URLs. You teach them relationships.

Consider in HTML ...

 <a rel="order" href="http://my.server.org/newOrder"/> 

and

 <a rel="order" href="http://my.server.org/nO"/> 

You will notice that rel is the same, "order", but the URL is not specified.

In the "ideal" world, the system will have a single entry point, say, http://my.server.org/ , and from there the client can find all the links that he needs to know.

In practice, many systems have several “well-known” and defined entry points from which the client can start, as well as the advisability that the client does not start from the root of the system. These well-known entry points imply a provider commitment that these URLs will not change anytime soon. They live for a long time, and the server will support them very well.

But once passing the entry point, any URL that you discover most likely does not have such a promise. A URL can be only one URL. It can be directed to different machines, for example, load balancing. Who knows. But as a consumer of the service, you really don't care what the URL is, you only care about the relationship. This relationship tells you the details of the URL used.

The documentation for your hypermedia API explains how to apply a single interface to each of the links your client will encounter. The client also cannot "intuitively", it needs to be trained.

In principle, teaching a client how to navigate in a relationship that he will or CAN find in useful data, he processes how the client manipulates the hypermedia API. The payloads contain iconic messages to show the path, but the server dictates where these messages go.

How often it is used, probably not very much in a machine for the machine world. Most systems are not large enough when URLs change so much that they matter and there are so few clients that changing clients is not a significant burden. Thus, the simplest code is missing.

But then, in the end, you just have bad customers. Nothing a REST system can do with a bad client. In any case, he cannot distinguish them at runtime.

Answer 2

Regardless of how you publish the API (which should be consumed by the machines), violations can be made.

When porting the API behind the user interface (for example, in HTML formats), you have the freedom to change the URI without violating the user, but this is because the user consumes the abstraction that you provided. Change the URL scheme without changing the form and you will break the client anyway.

Several ways to avoid tearing down client clients (mainly backward compatibility support):

• Building some type of URL versioning
• Redirect from old URL schemes to a new scheme

Answer 3

We quite successfully approached it as follows: we put the WADL file at the very root URL of the application, which describes the types of media , as well as where to look for links in it and their semantics . I know this (WADL) is something that is critical to some in the REST community, but I always felt intimidated solely by the orientation of the WADL URLs. Besides all the religious debate, we liked to have a well-defined way of documenting representations. There is a way around the WADL URL and rather indicate where the links can be found in the view and then document more quickly. See this blog post (currently unavailable due to maintenance, so you can view it in the Google cache ) for details on the approach.

This leads to the fact that the client can find out only one URL, because he can find out about this by contacting WADL, and then just find out about the view and where to find the links, which HTTP method needs which parameters when called, etc. d.