I would urge you to read more on the topic of real REST generally and hypermedia specifically. I fear with your emphasis you are leaning too heavily on a tangible definition of documents and missing at least some of the nuance which hypermedia provides to address the concerns you have.
The referenced ‘naive’ implementation is analogous to a poorly ‘normalized’ crud API, it requires and represents the extremely chatty nature described in your quote. However, hypermedia formats provide solutions to your concerns via JSON APIs includes parameterization for example to include all relevant relationships to reduce the chattiness.
I’ve already addressed the chattiness above, but you do make an excellent point in that a key benefit and concern of REST is highly decoupled client and server. However, I believe your concern is stemming from a naive approach to affordance definition (i.e. CRUD only or OAS). If your domain is getting that complex, I strongly urge you to look into the things I’m posting and linking regarding hypermedia. Creating a vocabulary which models the domain, and designing your API to match that vocabulary will greatly reduce the interface design complexity. You’ll have a 1-1 mapping of messages to send for complex actions to happen, which simply can not map into the CRUD / url partitioning pattern. It is quite OK for clients to have logic on them, in fact it’s encouraged as part of the REST dissertation, however the type of logic is key. You DO want your clients to have the logic to manage what they want to do, while you DON’T want your clients to have to contain the logic of HOW to do it (the business logic).
Yes, but I again caution you to avoid conceptualizing the resource as business documents as analogs to physical forms for processes. It is a very easy trap to fall into, but this leads you away from the many benefits of correctly defining the API interactions through your vocabularies. The complexity you describe is best handled by message representations, analogous to HTML forms, and is one of the primary benefits of vocabulary defined resource and message representations as it frees you of the burden of mapping complex processes to 4 methods on various resources.
It is imperative to understand that resource representations and message representations are two distinct concepts. Avoid letting the CRUD mentality slip over into a hypermedia service design. In CRUD the resource representation is the only message representation a resource accepts and understands.
Microservices is an entirely different discussion, but if you take my educational illustration and deploy them all as independent services you are of course correct it would be ridiculous - each service should be independent and self sufficient. That isn’t analogous to individual resources, which are very likely to be only a part of a larger complete service. However, to your deployment point on microservices, they will always require dependency management and orchestration. If you aren’t doing that, you are asking for trouble when nodes start to preform strangely and you don’t have visibility into the architecture.
Yes, that example was intentionally overboard to illustrate the point, I even said that a couple times to make sure nobody would take it at face value.
My arguments were intentionally generalized as this is a forum to discuss JSON API, I was not using it as a soap box from which to preach the solution as I see it. I make these statements as hints towards what my extensive research has shown me is actually the way forward through the difficulties we all share. Those items do make sense independently, and it would require you to understand why they make sense because it isn’t immediately intuitive. In that light I would invite you to read my guidelines on hypermedia APIs on my blog, the discussions of the individual points, as well as the comparisons to current approaches for a background information and summary of much of what I have read and listened to on the subject. I can assure you I have thought about a lot of these concerns previously and at great length while compiling the data for my hypermedia API work. Take a look, and I whole heartedly invite you to challenge my points and posts on this which don’t seem to make sense. I’m not omniscient and it is quite possible I have missed many nuanced concerns in my research.
The spec you are pointing to is the update portion and not delete. However addressing the delete method, nothing in there suggests you can’t send a new location header and new ETag for the resource which has expired. This can be utilized by caching layers, and clients to expire the now stale resource.
The compound document for the Order has changed, but the DELETE to line-item has succeeded, so the resulting response would be something like:
204 NO CONTENT
The message this sends is double meaning, but complete and adheres to the specification. In this example the server responds to the delete request by removing the resource, and returning the 204 status code with an empty body. However the headers to the response tell the story of the highest common denominator resource which can expire cached copies through intermediaries and ultimately on the client itself. The location of the effected resource is the cache key, and the new ETag would invalidate all cache copies along the way.
I said a few times I think this discussion was illustrative for educational purposes to understand the nuanced points I am making, and not necessarily an advocacy of an overly pedantic service. You are entirely correct, to remove all the convenience fields as I described them would be a pretty lousy idea in a real implementation.
Yes, 4 is not a random number, but a function of the power of 2.
You aren’t including the URL twice, but again increasing the complexity of managing the representations in two locations. While you’re trying to reduce the complexity of dealing with relationships, the result is actually a 4x increase in the difficulty - obviously not your intent.
I would advise you be very wary of ‘nounifcation’ of verbs in order to create resources which describe affordances, they are snowflake and almost always unintuitive to consumers. The better way would be to properly use a vocabulary of resources, affordances, and goals to handle the actions.
Regarding your statements about cache invalidation, you are obviously beginning to see why some of the most famous contemporary computer scientists consider it one of the most difficult problems to solve. To your first point, its possible to simply return resource identifier ‘objects’, and use them to invalidate the cached copies of resources in the client to ensure integrity while reducing the message size. Additionally, my previous suggestion helps to handle your second point and reduce the HEAD traffic for cache verification when there is a single resource you can return which is the lowest common denominator. It is likely this won’t always be the case, and you will be stuck performing duplicate calls on failed ETag validation and that simply is the nature of HTTP, it’s designed to fail elegantly.
I do agree this is wandering off topic, as this is directly related to the topics I discuss on my blog on hypermedia and not to JSON API, I would invite you to continue the discussion there with a link for interested parties to follow if they wish.