10

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?

Improve this question
2
  • 2
    The issue with discoverying a REST-service has been discussed and answered here: stackoverflow.com/questions/9101494/… The simplest solution is to use an XHTML template with a form that will not only tell about the method you can use but also the object structure to be sent through the form elements (input, select etc.). Clients only need to have a XML parser to find what they need. Another way is with URL Templates but they only help out with resources that take query strings.
    – Spoike
    Jul 8, 2013 at 11:41
  • Regarding content types; that is solved with content negotiation which is done in HTTP headers. If the server cannot serve a requested content type then it should return an HTTP error (such as 300 or 406) stating which content types it can return.
    – Spoike
    Jul 8, 2013 at 11:46

3 Answers 3

Reset to default
1

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.

Improve this answer
2
  • I think use of content type is the way to go; I could easily change my application to use application/atomapp+xml and make it available for all the clients that already understand this format. There are likely enough well-known content types out there to make this a practical solution.
    – Paul Turner
    Jul 8, 2013 at 12:02
  • I think the comment by @Spoike is an elegant REST-ian approach to the other half of the problem; even if the client knows that (for example) a user is represented as a vCard, it still needs to know what subset of the user's properties are available for searching on.
    – Stephen J. Anderson
    Jul 8, 2013 at 13:55
4

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.

Improve this answer
1
  • 1
    CXF is another big Java JAX-RS implementation that supports WADL, and you're starting to see a few interesting third-party WADL consumers now too.
    – Donal Fellows
    Jul 5, 2013 at 12:34
0

Spring has some support for this as does resteasy.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.