Understanding REST Entities (variations based on request and responses)

Question

OK so I have a few operations for my REST Web Service. There is some overlap of entities between the different operations but based on what I'm doing some of the elements/attributes are not relevant.

Eg. When I request rates I need to get back:

<Property id=””>
  <Rooms>
    <Room>
      <Rates>
        <Rate></Rate>
      </Rates>
    </Room>
  </Rooms>
</Property>

But when I just want to get a list of rooms back – I only want:

<Property id=””>
   <Rooms>
     <Room>
     </Room>
   </Rooms>
</Property>

and my get rooms request only requires as input

<property id=””></property> 

But based on the full definition of property - when I generate my sample getroomsRequest xml structure its including everything as per the top sample.

Am I supposed to be declaring different named entities? Or is there a way to use a common entity but somehow exclude stuff when it is not relevant?

Thanks! Not sure what is possible/best practice.

Answer 1

The reason that you are starting to have difficulty is because you are trying to create a direct mapping between your domain concepts (property, room, rates) and your REST resources.

In my opinion, REST resources should represent the use cases for your system, e.g. "Property/1/RoomRates", "Property/1/Rooms". The resources are more of a UI layer than a domain layer.

Some REST frameworks have started to implement mechanisms that allow you to specify on the query string exactly which pieces of data need to be returned. Again, in my opinion, this is a really bad idea. It severely limits the usefulness of caches and it creates more coupling between the client and server.

Do not have any fear of creating new resources in a REST system, even if it does not correlate to anything in your business layer. Most problems developers run into when designing REST based systems can be resolved by creating one or two new concepts as resources.