RESTful API design - should a PUT return related data?

Question

I have an API which allows a user to update their system status; and a separate call to retrieve system status updates from other users. Would it make sense to unify them under a PUT request where a user would request a PUT update with their own status update, and they would receive the status updates of other users?

My solution would allow the PUT request to call the GET request method internally. The reason behind this is that when a user updates their system status they should be informed of other users status immediately, and I don't feel that having 2 seperate requests is necessary - and should be optional.

I intend to keep the GET request for other users status as a status update for a user is not necessarily required in order to retrieve other users status', but once they update their own status is it vital that they get information about other users.

Answer 1

I don't think you should, for a few reasons:

• A PUT request it exactly that. They are sending you information and you should take it. You shouldn't change the semantics to "I'll take your data, if there's a mistake, I'll give you an error, but I'll also give you other data that you may or may not actually want or need.
• What guarantees do you have that every caller of the PUT request wants the related data?
  • The caller wants to send you 1 update a second, and retrieve related records every minute. Why waste bandwidth and CPU giving them data they don't want?
  • What if the request fails or is rejected (e.g. empty/missing status)? Do you still return the related data
  • How are you going to separate the related data from the return messages from the PUT request? Is this consistent with your other APIs?
• What is special about them updating then them getting updates about other users? Can't the two occur in parallel (i.e. they fire a GET and PUT at the same time?).

If you absolutely want this, you should make it an optional flag or call. If they specifically say fetchMeTheRelatedData then give it to then, but do not give it to them by default.