ADDR Define Phase Overview

The Define Phase identifies the scope and responsibilities of your APIs and encourages reuse by leveraging existing APIs.

Step 3: Identify API Boundaries

Using the activity steps and EventStorming canvas from the Align Phase, find the initial API boundaries. These boundaries help to decompose API products with large surface areas into smaller, cohesive APIs that make up the complete product offering.

Review your activity steps:

  • Watch for shifts in language that indicate a different boundary
  • Steps may offer hints with nouns or direct objects as a boundary starting point
  • Aggregates from an EventStorming canvas also provide hints to boundaries

Next, name each boundary. Avoid using “service”, “server”, or “manager” in the name as these terms fails to offer additional value or insight:

Once you name the boundary, group the activity steps by boundary – this creates an initial scope and responsibilities for the web API:

Example of two candidate API boundaries with associated activity steps supported: Grouping API boundaries

Expect your boundaries and API names to changeThroughout the design process, you may find that boundaries shift as will the names. Better to have this happen during design than after all the code has been written!

More details on identifying API boundaries may be found in Chapter 5 of the book.

Step 4: Model API Profiles

API modeling uses the artifacts created so far to define a high-level API profile. It is like creating a wireframe before detailed the full user interface. It brings together stories, activities, and steps into a unified API profile.

The API profile describes scope, intent, and operations that produce outcomes. The same API profile can be used to generate multiple API designs: REST, GraphQL, gRPC, etc. Along with the API profile, identify the set of resources and relationships between them.

Example API Profile with Resources: An API profile template

Finally, it is helpful to create one or more sequence diagrams that demonstrate how the API operations will be used to produce the outcomes defined in the associated job stories.

More details on modeling the APIs for each boundary may be found in Chapter 6 of the book.

At this stage, the API profile details what operations the API will need and the events it will broadcast. Next, the team transitions into API design.

Back to homepage