liveBook · Manning

Header interface

As explained in Clean Applications with Hexagonal Architecture

An interface shaped around the complete public method set of an implementing component rather than a specific client role.

A header interface mirrors the implementing class’s public API: its shape comes from the implementation rather than the application core’s needs. Used as an output port, it can leak infrastructure vocabulary into the core. A role interface instead expresses what the core needs from an external collaborator. section 5.2.2

Check an output port for implementation-shaped language:

  • Terms such as subject, body, recipients, cc, bcc, SMTP, or HTTP headers suggest the port mirrors a delivery technology. section 5.2.2
  • Define the port from the inside: keep only what the core needs, and let the adapter choose how to deliver it. section 5.2.2

Notification port

A header-shaped port exposes send(subject, body, recipients, cc, bcc). A role-shaped alternative asks the adapter to notify(text, type), leaving delivery details outside the core. 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.

The comparison shows how an implementation-shaped interface differs from a core-shaped role interface. section 5.2.2

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Defines the implementation-mirroring shape, contrasts role interfaces, and gives a vocabulary-based test for detecting leakage.
Examples
Contrasts an email-style send signature with a notify operation carrying text and type DTOs.
What you can do after
Evaluate ports for implementation-specific parameters and redesign them around the application core’s needs.
How it connects
Connects output ports, role interfaces, adapters, and the application core within hexagonal architecture.

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.