Subresources and relationships

I have posted this question before Clarification on Resources Composed of Other Resources so please review that thread. To summarize the 1.0 specification does not allow resources to be composed of other resources, i.e. having a resource in the attributes of another resource. Instead use resource linkage from the parent to the child where the child is added in the included part of the document.

The document is basically a flattened, one level list of resources with primary resource(s) and optional included resource(s) all linked together with resource linkage as documented in “full resource linkage” in the specification. The URL building of a resource truly being a child of another resource is done by the Hypermedia API implementation when building the resource self links and depends on the domain model of the resources for the system under consideration.

For example order, order items, and payments - the order items self links would always be under a parent order (self: /orders/1234/order-items/5678) as if you delete the order, the order items are also deleted via the whole/part design. But payments are associated to an order and would not be under order (self: /payments/9999). Again this is all implementation details which depends on the “domain model” of the resources for the system under consideration that are returned by your Hypermedia API server. But you could have a JSON API document with primary data of orders, and related order items and payments in the include section with resource linkage, etc.