# API-DD together with TDD, DDD and hexagonal architecture

## Different questions

API-DD does not replace these approaches. They can be combined when each retains its main question.

| Focus | Question that helps answer |
|---|---|
| DDD | What does the model mean and within what context? |
| Hexagonal architecture | What conversations connect the application with actors and technologies? |
| TDD | How do we grow behavior through actionable feedback? |
| API-DD | How do the modules communicate and what contract does each one offer? |

It is not necessary to adopt all four. The table serves to prevent a technique from answering questions that do not correspond to it.

## DDD brings meaning

DDD helps discover concepts, invariants, language, and model boundaries. When two areas use a similar word, it allows you to decide if they share meaning or need different representations.

API-DD can leverage that output to craft the conversations consumers need. It does not alone decide which model is correct nor does it require that work begin with DDD.

The reference used here is [*DDD Reference* by Eric Evans](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf).

## Hexagonal architecture guides conversations

A port represents a purposeful conversation; Adapters connect specific mechanisms to it. From API-DD, that port can be looked at as an API: messages, vocabulary, guarantees and effects.

Not every module needs to be converted into a port. Two internal modules can collaborate using a local API without representing an architectural boundary of the application. Converting each relationship to a port would add visibility and substitution without a real need.

The original intent of ports and adapters is described by Alistair Cockburn in [*Hexagonal Architecture*](https://alistair.cockburn.us/hexagonal-architecture/).

## TDD guides construction

TDD provides the feedback loop: choose the next behavior, write a test that fails, implement it and refactor. API-DD helps formulate that behavior as an observable guarantee of a module.

```text
contract guarantee → red → green → refactor
```

The test may discover that the contract was incomplete. In that case the decision is reviewed before continuing; the implementation is not forced to preserve a wrong specification.

The cycle is supported by the description of [Martin Fowler's TDD](https://martinfowler.com/bliki/TestDrivenDevelopment.html), based on the work of Kent Beck.

## Example in Go

Suppose a module needs to save and retrieve bytes per key. This API can act as an exit port when interchangeable providers exist.

```go
type Key string
type Value []byte

type Store interface {
    Load(Key) (Value, bool, error)
    Save(Key, Value) error
}
```

The hexagonal architecture orients this dependency towards the consumer's need. API-DD helps make visible decisions such as what absence means, who owns the returned bytes, and what errors should be distinguished. TDD allows those guarantees to be implemented one by one. If there will never be another provider or relevant boundary, a separate interface may be unnecessary.

## Frequent confusions

### Is every API a port?

No. Every port offers an API, but an API can also exist between internal modules that do not cross the application boundary.

### Does every module need a language interface?

No. An API can be expressed using a specific type, functions, methods, or messages. A technical `interface` provides when a consumer needs replacement or decoupling, not as a ceremonial requirement.

### Does API-DD prescribe a design order?

No. You can start with any module, rule or conversation whose contract and risk are clear. API-DD offers a perspective to review each module as an API, without prescribing a temporal direction to discover the system.

### Does a test with several modules stop being unitary?

The number of objects or modules does not determine what risk the test covers. It is more useful to declare the observed API and which implementations are involved than to discuss a universal label.

### Does watching an outgoing message break the black box?

Not when that message is part of the promised effect. Yes when there is internal collaboration that another correct implementation could resolve differently.

## A practical sequence

1. Use available modeling to clarify concepts and boundaries.
2. Identify the modules involved and the conversations between them.
3. Design each module as an API.
4. Formulate observable guarantees and choose the appropriate level of proof.
5. Deploy in small cycles and refactor without altering the contract.

The actual work will not be linear. A name discovered during a test can change the model; an architectural restriction may force you to revise the API. The separation of questions serves to understand the decision, not to impose rigid phases.

> **DDD clarifies meaning, architecture guides relationships, TDD guides change, and API-DD helps design the conversation.**