Take the 2-minute tour ×

For a SaaS startup I'm involved in, I am building both a RESTful web API and a couple of client apps on different platforms that consume it. I think I've got the API figured out, but now I'm turning to the clients. As I've been reading about REST, I see that a key part of REST is discovery, but there seems to be a lot of debate between two different interpretations of what discovery really means:

  1. Developer discovery: The developer hard-codes copious amounts of API details into the client, such as resource URI's, query parameters, supported HTTP methods, and other details that they've discovered through browsing the docs and experimenting with the API's responses. This type of discovery IMHO necessitates cool linkage and the API versioning question, and leads to hard coupling of the client code to the API. Not much better than if using a well-documented collection of RPC's it seems.

  2. Runtime discovery - The client app itself is able to figure out everything it needs with little or no out-of-band information (presumably, only a knowledge of the media types the API deals with.) Links can be hot. But to make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in. There are possibly other difficulties I haven't thought of yet since I haven't gotten to that point in development. But I do like the idea of loose coupling.

Runtime discovery seems to be the holy grail of REST, but I'm seeing precious little discussion about how to implement such a client. Almost all REST sources I've found seem to assume Developer discovery. Anyone know of some Runtime discovery resources? Best practices? Examples or libraries with real code? I'm working in PHP (Zend Framework) for one client. Objective-C (iOS) for the other.

Is Runtime discovery a realistic goal, given the present set of tools and knowledge in the developer community? I can write my client to treat all of the URI's in an opaque manner, but how to do this most efficiently is a question, especially over low-bandwidth connections. Anyway, URI's are only part of the equation. What about link templating in the Runtime context? How about communicating what methods are supported, aside from making a lot of OPTIONS requests?

share|improve this question
Just a slight aside on your OPTIONS reference. You can use the 'Allow' header to communicate permitted resource operations outside of an OPTIONS request. Roy Fielding goes as far as considering the header as a form of hypertext - see here. –  paulkmoore May 19 '12 at 14:37
tats a gr8 question, the key issues are given the list of applicable methods, should the client be able to form urls for the regular CRUD operation or will that be called as "out-of-band"? Say, if we provide links for CRUD operations as well, how do u do "form" s in json? May be if u r using application specific media types u dont need to do "forms", but wat is the standard way of discovering media-types(i.e json schema), will the process of discovering schema be considered as not "out-of-band" for clients?? –  redzedi Jul 29 '12 at 8:06
xhtml looks so good and fluid, but if u have to do json, tat i guess is rather amorphous now –  redzedi Jul 29 '12 at 8:07

7 Answers 7

up vote 22 down vote accepted

In this video Jon Moore builds a generic client using runtime HATEOAS auto discovery. It is pretty impressive and well worth watching:


share|improve this answer
Wow, thanks! This is the best discourse I've seen yet on the nuts and bolts of HATEOAS runtime discovery. I hadn't thought of using XHTML as my media type. I see a lot of advantages of that. –  curtisdf Feb 10 '12 at 17:24

This is definitely a tough nut to crack. At Google, we've implemented our Discovery Service that all our new APIs are built against. The TL;DR version is we generate a JSON Schema-like spec that our clients can parse - many of them dynamically.

That results means easier SDK upgrades for the developer and easy/better maintenance for us.

By no means the perfect solution, but many of our devs seem to like.

See link for more details (and make sure to watch the vid.)

share|improve this answer
Thanks! It's good to see Google taking steps to ease discovery of their own API's at least. Your link led to me discovering JSON-Schema which looks very helpful for validating representations submitted by client interfaces. I'm going to explore it. –  curtisdf Feb 9 '12 at 17:06
Is there any standart to implement such a discovery service for our own APIs? –  Çağatay Gürtürk Dec 21 at 18:20

Fascinating. What you are describing is basically the HATEOAS principle. What is HATEOAS you ask? Read this: http://en.wikipedia.org/wiki/HATEOAS

In layman's terms, HATEOAS means link following. This approach decouples your client from specific URL's and gives you the flexibility to change your API without breaking anyone.

share|improve this answer
Thanks for reminding me about HATEOAS. That seems to be the keyword I was missing to help me figure out what to do with my client interfaces. (Man, I really dislike that acronym!) I'd come across HATEOAS before, and I guess I internalized what it meant but I forgot to use the name in my searching. I see lots of resources now that are giving me a better picture, and some hope that it's not unattainable after all. –  curtisdf Feb 9 '12 at 17:14
ios samples ? what did you choose ? at some point you need to know what you are looking for! so you need to know the API so you need to hardcode some stuff ! –  Vassily Sep 27 '12 at 13:21
@curtisdf Completely off topic, but instead of saying that you really dislike it, shoulda said you HATE- it... HATE-OAS... :) Sorry, couldn't resist –  jamiebarrow Feb 18 '13 at 21:00
@jamiebarrow Ha ha. Yeah, HATEOAS is appropriately named. :-) –  curtisdf Feb 18 '13 at 21:49

You did your home work and you got to the heart of it: runtime discovery is holy grail. Don't chase it.

UDDI tells a poignant story of runtime discovery: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration

share|improve this answer

I think the important point about HATEOAS is not that it is some holy grail client-side, but that it isolates the client from URI changes - it is assumed you are using known (or developr discovered custom) Link Relations that will allow the system to know which link for an object is the editable form. The important point is to use a emdia type that is hypermedia aware (e.g. HTML, XHTML, etc).

share|improve this answer

For another example of a basic runtime discovery client, check out the HAL Talk Hypermedia API client demo.

Based on the Hypertext Application Language (XML+JSON schema for linking): http://stateless.co/hal_specification.html

share|improve this answer

You write:


If that link template is supplied in the previous request, then there is no out-of-band information. For example a HTML search form uses link templating (/search?q=%@) to generate a URL (/search?q=hateoas), but nothing is known by the client (the web browser) other than how to use HTML forms and GET.

share|improve this answer

Your Answer


