factor10 Solution Designer

Field notes

Endpoints

External endpoints and events are the public commitment a Bounded Context makes to the outside world. Everything else can change freely: the data model, the persistence, the internal language. The external endpoint and event contract cannot. Being explicit about what is exposed (and thereby implicit about what is not) is the difference between a Bounded Context you can maintain and one held hostage by every consumer it has ever had.

List the endpoints the current Bounded Context exposes. Keep the field list close to the contract you actually intend to publish. Keep it minimal.

As usual, the "best guess" level is what we are after here. Precision is best pinned down during implementation. That said, it can be worth describing internal endpoints and events too (including events we subscribe to), to capture something important and help certain stakeholders reach shared understanding, but that is usually of lower priority.

 

Things to consider

• Endpoint is often related to an aggregate root. That can be a good way to
  think in order to get started.
• Verb: the HTTP verbs (GET, POST, PUT, PATCH, DELETE) carry semantics when
  it is a REST API. We have chosen to let Events use Verb as their form of
  description too, for publish and subscribe.
• Multi-tenant: if the system is used by several different organisations in
  the same instance, the contract should make clear how tenancy is expressed
  (path prefix, header, subdomain or token).
• Versioning: endpoints may need to be versioned. Decide a strategy (URI
  version, media type, header) early.

 

Further reading

• Webber, J., Parastatidis, S. & Robinson, I. *REST in
  Practice: Hypermedia and Systems Architecture* (2010)
• Evans, E. Domain-Driven Design (2003)
• Vernon, V. Implementing Domain-Driven Design (2013)