liveBook · Manning

Role interface

As explained in Clean Applications with Hexagonal Architecture

An interface whose operations express the specific capabilities required by its consumer rather than the full API of an implementation.

A role interface defines an output port around what the application core needs from an external collaborator. Unlike a header interface, it does not mirror the implementing class’s API or expose delivery-specific vocabulary. section 5.2.2

Design the port from the inside out:

  • Express the core’s need in application vocabulary, not terms tied to a delivery technology. section 5.2.2
  • If parameters make sense only for one implementation, redesign the interface; implement the core-owned port in an outer adapter. section 5.2.2 section 5.5

Notification port

A role interface can expose notify(NotificationTextDTO, NotificationTypeDTO) rather than send(subject, body, recipients, cc, bcc). The adapter decides how to deliver the notification. section 5.2.2

Figure 5.4 The header interface on the left is shaped by the email implementation. The role interface on the right is shaped by what the application core needs, keeping the port technology-agnostic.

Compare an implementation-shaped header interface with a consumer-shaped role interface. section 5.2.2

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Contrasts consumer-shaped ports with implementation-mirroring interfaces and demonstrates both through notification signatures.
Examples
Compares email-shaped send parameters with a notification operation that accepts text and type DTOs.
What it assumes
Assumes an application core that needs external collaborators through output ports.
What you can do after
Build it from scratch: define ports from core needs, then implement them in outer adapters.
How it connects
Connects role interfaces to hexagonal architecture, output ports, and adapters.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.