Link

Nexus Profile

Profile: <http://level3.rest/profiles/nexus>

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.

Discovery

The Nexus profile presents the required Profile and Allow headers. If the resources offers no state data, it will return 204 No Content.

Fetch Nexus

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.

Remove Nexus

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.

Specifications

HTTP/1.1 Semantics and Content: RFC 7231


Copyright © 2019 Matt Bishop
Creative Commons Licence
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.