Non-contextual operations using REST and HATEOS

Question

I am trying to implement HATEOS based REST service for hotel booking but have this confusion:

1) How does apart from WADL, the client comes to know about possible operations and their corresponding URI. Should I put all possible operations and URI as response when the client hits the root of REST service?

2) When the client gets a list of all accommodation options in an area, I am returning a list of all hotels in the area he asked about. The response contains:

<accommodation>
  <hotel info="http://welco.me/hotel/xxxxxx" price="5000"/>
  <hotel info="http://welco.me/hotel/yyyyyyy" price="3000"/>
</accommodation>

But the query I have here is how the client is going to know about other related possible operations like getting the list in sorted order of price?

Answer 1

1. In answer to your first question, there are a couple of specs for documents that allow clients to discover RESTful APIs.

• Swagger
• JSON Home
• Google use their own Discovery Service, however unlike Swagger and JSON Home, unfortunately I don't think there are open sourced libraries that help you use expose it for your own APIs.

2. For Your second questions again, I would tend towards clients/developers discovering parameters such as sorting from the Swagger/JSON Home document. However if it is a super strong/important relationship you could also return it in the responses as linked data:

• In HAL you can provide a links object with links to related resources.
• In JSON-LD you can add a field with a value of the related API url. You may then add an @content to add information describes what that relationship means.

Answer 2

1. You should use link hints. An older way of doing this, the OPTIONS method, has some longstanding caveats.

2. Include links that use a custom link relation something like http://welco.me/#sort-by-price where you define the URI to mean whatever you want it to. You should provide some developer documentation at that URI but the client app will never dereference it, it merely uses the URI as an opaque string for equality comparisons.