Domain-driven design is essential for establishing quality developer experiences — even for internal platforms. “All APIs deserve equal love,” said José Haro Peralta, Consultant, microapis.io. And according to José, domain-driven design is a great strategy to ensure your APIs are easier to understand and consume.

At Platform Summit 2023, José Haro Peralta will highlight the benefits of domain-driven design.

Ahead of the Platform Summit 2023, we’re interviewing some key speakers to explore their upcoming talks and gather perspectives on the state of the API economy and what they’re working on.

José Haro Peralta, a Platform Summit speaker, is an author, consultant, and instructor based in London. He’s the author of Microservice APIs, the founder of microapis.io, and lead maintainer of fencer, an automated API security testing framework.

At the Platform Summit, José will explore how to model APIs with domain-driven design. I caught up with him before the event to learn more. Below, we’ll consider how taking a domain-driven design approach can benefit APIs and some tips to get you started on setting the right boundaries for these services and their related schemas.

Most API Designs Are Too Implementation-Focused

The general problem with API design, expressed José, is that we tend to think very strongly from an implementation point of view. For the sake of convenience, developers often create similar schemas across their microservices and API portfolios. However, the problem is that these schemas often become convoluted and overloaded and may even end up representing different types.

When you start to combine models in the same schema, then you end up with a schema that’s difficult to run data validation on, let alone understand what you’re dealing with, described José. And this isn’t only a REST-centric design problem — it can affect other styles, from GraphQL to gRPC.

“The API is an interface, not just a combination of endpoints and payloads.” Instead of designing around implementation details, José encourages API designers to consider the processes and flows they want to model and to treat the API as more of an interface.

Domain-Driven Design Aids Developer Experience

Domain-driven design helps “incorporate the language of business into software,” said José. This means first starting with the concepts, processes, and flows, considering their operations and semantics, and then implementing the design. Instead of adopting randomized URLs, you create URL hierarchies that represent specific operations in the bounded context.

For instance, consider an insurance platform with two distinct functions: /payments and /claims. Since they are different business operations with distinct data heuristics, they really should be separated into their own APIs with their own schemas. This sort of design approach makes much more sense than using reusable, generic schemas, which become hard to map to specific entities, said José. Keeping schemas within bounded contexts avoids tight coupling and makes them easier to evolve over time, he added.

Adopting Bounded Contexts Improves Security

One significant benefit of domain-driven design (DDD) is that, from an architectural perspective, it’s simpler. Having one schema per entity makes data validation easier, and more accurately structured URLs aid relatability and maintainability. “You know where something belongs, and you know which endpoints you need to look at to extend functionality,” said José.

This is opposed to convoluted endpoints with schemas representing multiple entities, which can negatively affect security. With more underlying business logic, more combinations of properties and values will be valid, thus heightening the likelihood of malicious payloads. “Having very constrained schemas means the user has fewer choices to add all kinds of properties and fewer chances of hijacking the API,” said José.

Having more unique schemas can prevent unwanted introspection as well. For example, consider a car-sharing application with IDs for drivers and users. If the same schema is reused for all contexts, attackers will know how to craft many more types of requests, which could potentially over-expose information in the case of broken object-level authorization. Furthermore, the schema that is exposed through documentation should reflect the privileges of the target user, whether they’re administrative, internal, or external users.

How Granular Should We Get?

Another consideration is: where exactly are the boundaries between individual APIs? And if APIs are well-defined, how granular should we get? APIs and their associated schemas should be correlated to how you define the entity and the operations you perform with the API, said José. This will be determined by the business flows and what information they’re carrying in each operation.

Another concern of well-defined APIs is inter-communication. APIs with well-defined schemas can make integrations easier for specific contexts. Yet, one tradeoff of decoupled architectural designs is that you must often link up components so they can talk to one another to initiate a series of steps. So, how can API designers represent serial business flows?

Well, in OpenAPI 3.0, there is the concept of Links, which enables API definitions to describe how values returned by one operation can be used to initiate other procedures. This can help describe the relationships between various well-defined endpoints, said José.

The Workflows Special Interest Group is also defining a way to express specific sequences of calls within the context of an OpenAPI definition. Seeing the user journey between these entities could help usability a lot.

Lastly, with more schemas comes more problems… and more potential for API sprawl. Of course, there will always be a tradeoff between reusing schemas and creating new endpoints and schemas, noted José. It might be worth it for existing properties to reuse an existing one. But for the most part, he believes that well-defined scopes will help lower maintenance hurdles overall.

Learn More At Platform Summit 2023!

“I’m very excited to meet all the API developers and thinkers at the conference and exchange ideas,” said José. “The experience of a physical conference is a big difference compared to online events. It’s great for talking, making sure ideas don’t fall through the cracks, and making connections.”