Handling Restful services

Question

I've been wondering about a good approach to implement (actually bind) a restful services as a client.

You often see code snippets where the URL-"string" gets concatenated in high-level code, which obviously is very messy.

like

 "http://service.url/firstname/" + $firstname + "/surname/" + $surname

What would be a proper approach to do this?

To me this problem is way easier solveable with classic-rpc (JSON/XML-RPC) approaches, where you have can have a contract and you can be stricter about what you expect.

Thank you!

-Alessandro

Answer 1

The REST answer is that you shouldn't be building URLs. In a system following the REST tenants, you are following links to resources which have been provided for you buy navigating the hypermedia of the system. You start at a reasonable well-known URL as the root of your navigation and walk through the resources from there.

This is known as HATEOAS - Hypermedia as the Engine of Application State. It is one of the REST architecture constraints.

The significant advantage of this constraint is to decouple the client from the API to the extent that the API can change its URL scheme at any time and the various clients will not have to make similar changes. Requests to "old" URLs get served with 300-range errors and the new URLs gradually populate into their caches.

As far a performance goes, it's reasonable to cache these URLs, provided you honour the 300-range of codes and update the cached URL appropriately.

This means that if you wanted to get to a particular user with a given name, you would assume you already had their URL cached, or that you had a mechanism (like OpenSearch) to find a user meeting the criteria. You wouldn't "build" the URL, unless the service provided you with a template for you to populate.

You can find a good educational example of a REST service at http://www.thomas-bayer.com/sqlrest/. Your browser is a good enough client to interact with the service and should demonstrate how it is possible for any client to discover the resources of a system by following Hypermedia formats.