Just thought I'd add that a lot of people are raising the issue of discoverability in restful services. From what I have read this is dealt with with three key constraints: mediatypes, link relations and HATEOAS (hypertext as the engine of application state).
Mediatypes provide a standardised way of processing the representations provided to and from a resource (HTML is processed in particular way, as is JSON, as are PNGs, etc). REST has a constraint that requires you use registered mediatypes. On the web, this is the IANA (http://www.iana.org/assignments/media-types/index.html). If you mint your own mediatypes and use them on the public web, they must be registered with IANA for a service to be considered RESTful.
Link Relations again provide a standardised way of manipulating resources. They describe how resources at the end of a link can be manipulated. Examples include the ATOM edit relation, others include the stylesheet relation.
HATEOAS is a constraint that demands that the the client application should move between states by processing the hyperlinks contained within a representation via the relations provided.
There are two things you should pick up from this: a general REST client will not be able to do much with a service without knowing how to process the mediatypes of the representations returned by resources, and will not be able to move between states on the client without understanding how to interact with the service via the relations the service uses. Think about the most common REST clients out there: web browsers. If I mint a new mediatype that represents "a visual representation of a kitten with a comical caption", I cannot realistically expect a web browser to understand how to process this. The knowledge of how to process my custom mediatype must be baked into the web browser, much like web browsers know how to process image/* media types.
Much the same problem exists with link relations. Most of the time Link Relations are defined with a mediatype (think how a web browser must move to the state of processing a stylesheet by understanding that the link rel "stylesheet" dictates that the user-agent must retrive the stylesheet resource by performing a HTTP GET on the linked resource).
RESTful client applications must be able to understand the mediatypes and link relations used in a RESTful web service.
These three separate constraints, constraints that must be adhered to to be considered RESTful allow a REST client to navigate a REST service. The beauty here is that the service may change the url space of a service at any point without breaking a client, as the client knows all it needs to know to safely move around the client application state, as the rest is provided by the service on a per request basis.
As others have pointed out, caching (another constraint) cuts down on the constant round trips that such a setup would suggest, but I'll leave that constraint for another commenter to flesh out :)
Finally, two points: HTTP headers are part of the representation. This means that mediatypes that may at first appear to violate the hypermedia constraint can be made into hypermedia representations via the link header (http://tools.ietf.org/html/draft-nottingham-http-link-header...). So PNGs can link to resources that contain metadata with a link relation such as "meta" (for example).
Second, many people mention the common HTTP verbs but ignore the OPTIONS verb. Calling OPTIONS on a resource can provide a lot of information back to the client about how they can interact with a resource. I've built systems that provide a list of HTTP verbs that a logged in user may perform on the resource, for example. Different users with different roles may be able to POST or DELETE, whilst others would see that they can only GET.
Hopefully this sheds some light on how RESTful services are made discoverable.
What syntax should one use to define link relationships in a RESTful service?
Most of the examples I've seen extolling the virtues of HATEOAS use XML, specifically the <link uri="..." rel="..." /> element. That's great for a single media type (XML), but what about JSON, which is by far the dominant media type used in RESTful APIs?
reveals...a bunch of people asking how to format link relations in JSON, without a definitive answer that I can see.
HATEOAS and discoverability are principles that sound great in high-level discussions but I have yet to see them implemented in a meaningful, helpful way.
Anyhow, you seem quite knowledgable on the subject so perhaps you can enlighten me. Usually it's my own ignorance/obstinateness that's to blame rather than a flaw in the concepts themselves...
I would argue that you don't. JSON isn't a format for HATEOAS, for the reason you state. I'm leaning towards saying HTML 5, with some of the new semantic markup, though it's not perfect.
You can use both, and simply use the Accept HTTP header to determine which format you want. It gives you both discoverability of HTML (with <a>), and data transfer that is easy to parse.
I agree, I too have seen lots of discussions of how to format links in JSON. As you noted, JSON is not a hypermedia format per se, but if you use the Link HTTP header you can add hypermedia to non-hypermedia mediatypes. Here is a quick example:
HTTP Response:
HTTP/1.1 200 Ok
...
Link: <http://example.com/some-resource>; rel="edit";
title="Edit some resource"
Content-type: application/json
{"prop":"val"}
You should be able to see that the link header contains a target url, a relation and optional title. The Link header maps almost exactly to the HTML Link element.
I agree, I havent seen a "true" RESTful service either, except for very simple examples. As others have noted, REST is quite a difficult architectural style to summarise in a few short pithy statements, which leads a lot to the confusion on implementation. I also think that the fact that the architectural style is defined by constraints, which traditionally flies in the face of all previous architectural styles I have seen, which emphasise features and what you CAN do. REST is about what you DONT do. Its these restrictions that combine to make something very powerful, flexible and scalable. Think chess: its a stupid game with a board limited in size, the pieces all move in complicated but specific ways. It cant possibly be an interesting and deep game with all these constraints!
If you are interested in discussions on the subject, I recommend joining the rest-discuss mailing list on Yahoo Groups. Sure the conversation veers into hand-wavy, ivory tower territory, which can be forgiven seeing as the discussion group is for exactly this, but you get some very comprehensive and detailed explanations. Definitely search the archives because a lot of stuff has been answered in great detail before. Roy Fielding even pops on sometimes to correct a few points, and you dont get much more authoritative on the subject than that :)
Mediatypes provide a standardised way of processing the representations provided to and from a resource (HTML is processed in particular way, as is JSON, as are PNGs, etc). REST has a constraint that requires you use registered mediatypes. On the web, this is the IANA (http://www.iana.org/assignments/media-types/index.html). If you mint your own mediatypes and use them on the public web, they must be registered with IANA for a service to be considered RESTful.
Link Relations again provide a standardised way of manipulating resources. They describe how resources at the end of a link can be manipulated. Examples include the ATOM edit relation, others include the stylesheet relation.
HATEOAS is a constraint that demands that the the client application should move between states by processing the hyperlinks contained within a representation via the relations provided.
There are two things you should pick up from this: a general REST client will not be able to do much with a service without knowing how to process the mediatypes of the representations returned by resources, and will not be able to move between states on the client without understanding how to interact with the service via the relations the service uses. Think about the most common REST clients out there: web browsers. If I mint a new mediatype that represents "a visual representation of a kitten with a comical caption", I cannot realistically expect a web browser to understand how to process this. The knowledge of how to process my custom mediatype must be baked into the web browser, much like web browsers know how to process image/* media types.
Much the same problem exists with link relations. Most of the time Link Relations are defined with a mediatype (think how a web browser must move to the state of processing a stylesheet by understanding that the link rel "stylesheet" dictates that the user-agent must retrive the stylesheet resource by performing a HTTP GET on the linked resource).
RESTful client applications must be able to understand the mediatypes and link relations used in a RESTful web service.
These three separate constraints, constraints that must be adhered to to be considered RESTful allow a REST client to navigate a REST service. The beauty here is that the service may change the url space of a service at any point without breaking a client, as the client knows all it needs to know to safely move around the client application state, as the rest is provided by the service on a per request basis.
As others have pointed out, caching (another constraint) cuts down on the constant round trips that such a setup would suggest, but I'll leave that constraint for another commenter to flesh out :)
Finally, two points: HTTP headers are part of the representation. This means that mediatypes that may at first appear to violate the hypermedia constraint can be made into hypermedia representations via the link header (http://tools.ietf.org/html/draft-nottingham-http-link-header...). So PNGs can link to resources that contain metadata with a link relation such as "meta" (for example).
Second, many people mention the common HTTP verbs but ignore the OPTIONS verb. Calling OPTIONS on a resource can provide a lot of information back to the client about how they can interact with a resource. I've built systems that provide a list of HTTP verbs that a logged in user may perform on the resource, for example. Different users with different roles may be able to POST or DELETE, whilst others would see that they can only GET.
Hopefully this sheds some light on how RESTful services are made discoverable.