When building a REST service with the HATEOAS constraint, it’s very easy to advertise the existence of resources through linking. You make a GET to the root of my site and I respond with the root document listing all the first-tier resources:
{
users: { href: "/users" }
questions { href: "/questions" }
}
Clients which understand how to read these href values could perform GET requests on those and discover all the current resources available in the application.
This works well for basic lookup scenarios, but doesn’t indicate whether a resource is queryable. For example, it may be reasonable to perform:
GET /users?surname=Smith
Are there any formats that could express this query ability with enough information that a client could form a coherent query without needed prior knowledge of the resource?
Additionally, is there any way to express that a client is allowed to perform a POST to a given location with an expected location. For example, it could be expected that a client perform the following to create a new question resource:
POST /questions
{
title: "Are there strategies for discovering REST services using HATEOAS?",
body: "When building a REST service with the HATEOAS constraint, it's very..."
}
When using HTML as the format for human consumption, we can express a lot of this through use of forms and written prompts to allow a human to discover the operations they are allowed to perform on a service.
Are there formats which are capable of similar things for clients?
2
How would you know what kind of inputs are acceptable? That is to say, if your client has no prior knowledge, how would you define the semantics of “surname”? You’re starting to get into the territory of needing something like OWL.
I think it’s more practical to expect your clients to understand the semantics of well-known mime-types; say, for example, “text/vcard” for people.
2
You can publish details on your services through a “WADL”
http://en.wikipedia.org/wiki/Web_Application_Description_Language
It’s optional and not every backend REST technos supports this. Jersey, the “official” java implementation of jax-rs, supports it for example – it can be automaitcally generated for you.
It’s quite rare though, to see it used.
I don’t know of big ones using it. In general you have a web page describing the api.
1
Spring has some support for this as does resteasy.