How should REST resources relate to the server database schema?

Question

I am trying to understand whether resources in a RESTFUL API should directly represent the underlying database or not. In particular, a problem that I have is that I usually use highly normalized databases. The result is that if my API always hyperlinks to the children of a parent resource then the network will be unmanageably chatty.

According to the accepted answer here: https://stackoverflow.com/questions/12758219/pure-hateoas-vs-making-too-many-service-calls there is nothing in REST which prohibits child resources from being nested in the representation of their parent resource. However, Roy has also had this to say:

Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources).

(https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven comment 5)I can only interpret this to mean that child object should not be nested in the representation of their parent objects (if they are, then we have a 'list of object representations').

A priori it seems to me that having a total coupling between my database schema and my API design is bad. It forces me to consider network implications when designing my schema. But I want to design my schema based only on normalisation considerations. On the other hand, I can see how too much nesting can reduce the ability to scale the application while maintaining a navigable API.

Is there anything in REST which talks directly to the relationship between which objects are resources that must get URIs, and the database representation? Or do I am I misreading things? Thanks.

Answer 1

How should REST resources relate to the server database schema?

Not at all. The REST architectural principles are completely independent of the technology that is used to persist information. It is entirely possible to create a REST API without any database behind it (and that is exactly what a webserver serving static pages does).

---

However, Roy has also had this to say:

Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources).

(https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven comment 5) I can only interpret this to mean that child object should not be nested in the representation of their parent objects (if they are, then we have a 'list of object representations').

What Roy Fielding is arguing for is that if I ask for a list of parent objects, then I should just get a list of links to those parent objects, possibly augmented with summary information that makes presenting the list to the user less chatty.

If I ask for a single parent object, then it depends on the logical relation with the child objects if those child objects should be included directly in the response or only through a link. This determination should be based on how the user of the API and/or the business looks at those objects and not on how they happen to be implemented in the database.

To take StackOverflow as an example, there is a parent-child relation between questions and answers. Most likely, they are stored in separate tables in the database.
If we consider the website a REST API that serves HTML content (which is a simplification), then the homepage shows a list of questions with links and some summary information (like the title, question score and number of answers).

When you visit the link for a single question, you see the whole question, including child objects such as answers. On the other hand, you also get some "child" objects, such as related questions in the sidebar, as links.