As I’ve discussed before in this blog, REST is an architectural style for building distributed hypermedia applications much more than a way to simplify APIs. Essentially, REST takes the idea of the Web itself and abstracts its properties into a general set of architectural constraints that can apply to a broad range of distributed computing problems. However, thinking about distributed applications as hypermedia applications can require a change in the way developers and architects think about their applications.
For example, REST handles service discovery very differently than traditional approaches like SOA. With SOA, deployments centrally manage service metadata in repositories. To discover a service, access the metadata in the repository. With REST, however, each representation contains all the metadata you need (the self-descriptive messages constraint). To discover a RESTful service, follow the appropriate hyperlink.
When the client is a browser, following hyperlinks is a no-brainer. But REST abstracts the client, so now, it could be any piece of software you like, with or without a user interface. Even so, for your client to discover the capabilities of a resource (or set of resources), it should follow hyperlinks in representations it obtains from those resources.
At this point in the explanation developers usually give me a confused look. Humans clicking links is one thing, but how does my program know which links to click, and what to do with the information it gets from the resulting representations? The answer once again is the self-descriptive messages constraint: it’s up to the resource to provide sufficient metadata in every representation so that the client knows what it can do next.
The resource must be able to provide representations in Internet media types (aka MIME types) appropriate to the client. Returning an HTML representation, therefore, is probably not the best idea, since HTML is designed for rendering in a browser for human consumption. So, which Internet media type should you return? The architects answer: it depends — it depends on what you are trying to accomplish with such interactions. There are many choices available, and clients may negotiate with resources regarding the Internet media type they require.
