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.