img
Home > Candidate Patterns > Entity Endpoint

Entity Endpoint

img

How can entities be positioned as reusable enterprise resources?

Problem

A service consumer that wants to interact with an entity such as an invoice needs to maintain two identifiers: One for the service and another for the invoice. Capabilities are invoked by sending a message containing the invoice identifier to the service endpoint identifier. This message conforms to a service-wide contract that is scoped beyond the entity itself and contains all information relevant to accessing all capabilities of the service. The entity identifier is typically unique only within the scope of the service endpoint identifier, leading to consumers needing to manage a compound identifier for the invoice consisting of both the service endpoint identifier and the invoice identifier.

Solution

Expose entities as individual lightweight endpoints of the service that they reside in.

Application

Break up the service contract to expose service capabilities over individual lightweight endpoints. The contract exposed by each endpoint expresses capabilities that operate only over the conceptual entity. Service consumers refer to the entity using the corresponding endpoint identifier. All messages exchanged by services refer to the entity using its endpoint identifier.

Entities may "overlap" in order to offer capabilities at multiple levels of granularity. For example, an invoice and properties of the invoice can be exposed as separate entity endpoints even though they refer to a common set of underlying information or functionality.

Impacts

Finer-grained endpoints implies that more endpoint references must be maintained, and a greater burden can be placed on composition controllers to identify endpoints correctly as part of fulfilling their function.

Governance demands and the complexity of the solution can increase significantly if endpoints have their own distinct contracts. Combine with Uniform Contract to reduce this overhead.

Greater effort may be required in developing a Service Façade that relates endpoint capabilities to core service logic.

Status

Under Review

Contributors

Raj Balasubramanian, Benjamin Carlyle, Cesare Pautasso

Exposing conceptual entities as fine-grained service endpoints reduces the size of the contract exposed to individual consumers, and reduces their need to maintain context-sensitive entity identifiers.

img

Making use of a uniform contract for entity endpoints means that service consumers are able to discover lightweight endpoints at runtime and readily interact with them.