Is it okay for a POST response to return resources other than those in the request?

Question

Working on the API, I understood that the behavior for one of the endpoints might be a bit counter-intuitive, but I am not sure whether this violates any RESTful rules. Based on what I have read, it doesn't directly but probably that's a bad practice anyway.

I have an endpoint, say, /items for which there are two methods: GET (returns all existing entries) and POST (creates a new entry).

This is not a straightforward CRUD because getting an item results in a query that joins several tables and returns them in a user-friendly manner.

Creating an item requires sending a payload with a list of objects (not of type item).

Intuitively, it seems that the most logical way is to expect an object you want to create and then receive it in the response. In my case, however, the payload in the request contains the list of objects that are used to correctly create an item that can further be returned (and it will be an array of objects because there might be several rows created as a result).

To sum up:

1. Is it okay for a POST request to send objects in the payload other than what you expect to be created?
2. Is it okay to return an array of objects (I assume the answer is most likely yes)?

I know that POST requests are often used for all non-standard types of requests but I would like follow the best practices as long as possible :)

Answer 1

TL;DR Neither REST nor W3C are concerned with what your resource representation may contain. (the answer to both questions "is it okay" -- Yes)

---

For reference, Roy Fielding's original dissertation which outlines the set of principles known as 'REST' can be found here: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

The dissertation has a definition for the term resource under 5.2.1.1 Resources and Resource Identifiers:

"Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on."

(bolded emphasis mine)

Note that Fielding's dissertation does not make any explicit mention of HTTP verbs.

The semantics of HTTP verbs such as GET, PUT and POST are defined by the W3C HTTP specification, and not extended by REST, those verbs are typically part of what REST terms as 'interactions'.

The W3C specification does not in any way restrict the semantics around 'what' the body of an HTTP POST request may or may not represent.

REST places very few requirements on the semantics of an interaction (beyond those defined in the HTTP standard); principally it requires all interactions to be stateless, secondly it expects resource identifiers to consistently identify the same resources -- i.e. the same identifier must not identify different resources between interactions.

Beyond this, REST does not place any restriction on the semantics of interactions - REST is sometimes incorrectly cited as being based around CRUD semantics, however Fielding's dissertation does not include any such expectation.

REST describes the concept of a resource representation in 5.2.1.2:

A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.

In short, Fielding's dissertation about REST is focused on consistent identification of resources and not around the resources themselves; REST is concerned with resource identifiers always being able to consistently identify the same resource, and with stateless interactions.

---

Footnote: I think it would be worth a note that simply following REST principles only provides a rough starting point with respect to API design; REST may not care about the semantics of your resource representation, but your users almost certainly will. I believe it's important to get feedback on those semantics from people who will consume it, and try to design around their preferences.

Answer 2

Short: You can return whatever you like, provided you tell the client what it is.

In REST all messages are self-descriptive. For HTTP requests and responses it means that messages indicate what they are, using media-types. Clients are actually not allowed to expect any specific representation in responses at all. In effect a proper REST client must be able to process whatever media type it receives, regardless when they receive it.

To give you an example: If you make your POST request and the server in the response redirects you to a "login page" (or straight gives you the login page) then back to your "result", the client should be able to handle that, provided all the media-types used were known to the client before the interaction.

This is in fact how a lot of web (i.e. RESTful) applications work. For example: amazon giving you the login page somewhere in response to you ordering or trying to pay. Even though those were made for humans, "APIs" should actually work the same way.