A Nexus resource is a central “meeting point” for related resources. It is often identified by a shared business identifier, like invoice number or a book’s ISBN. A Nexus resource may have state information, but it is read-only and should reflect an overall business state. For instance, an order resource can have the states “open” or “closed.”
Clients discover related states via the links attached to the Nexus. The order resource’s shipping details, payment info and other order-related states are related to the Nexus resource but are linked, not embedded, in the Nexus resource. These resources offer affordances to manipulate the state of the order.
A Nexus resource offers the
DELETE operation which removes the Nexus resource instance from the system. Related resources remove their states as a result of a successful delete.
The Nexus profile presents the required
Allow headers. If the resources offers no state data, it will return
204 No Content.
A client can fetch the Nexus’ state with a
GET request. The state information is in the payload. If the resource has no state, it will return
204 No Content instead of
200 OK and a state body.
Nexus resources, as central points of business context, might not be entirely deleted by the underlying system. Subsequent calls to the removed Nexus can return
410 Gone to indicate it did exist once but no longer. An API should not represent a
DELETE result as a terminal state like ‘deleted’ but should instead make a state transition to this final state as part of its workflow.
HTTP/1.1 Semantics and Content: RFC 7231
- 200 OK: section 6.3.1
- 204 No Content: section 6.3.5
- 404 Not Found: section 6.5.4
- 410 Gone: section 6.5.9
Copyright © 2019 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.