APIs for Modern Commerce

Chapter 2. Modeling APIs

When building applications, start by first modeling your APIs. Then write the application(s) to back those APIs. Modeling APIs involves selecting the representation format (typically JSON or XML), defining the various resources (objects like /Product, /StoreLocator, etc.), modeling each resource’s attributes (e.g., key/value pairs like productId="12345"), and finally modeling relationships to other resources (e.g., <link rel = "customer" uri = "/Customer/c12345" />) It’s similar to defining an entity relationship diagram (ERD) for your database before writing a monolithic application.

When you model APIs first, you’ll find that it’s easier to write the application. Often, individual resources (e.g., /Product) map back neatly to individual microservices. If you start by writing your application and then retroactively expose functionality and data through APIs, you’ll end up with APIs that mirror your application’s idiosyncrasies rather than a well-thought-out API that is easy for developers to consume.

Note

How granular should your APIs be? Check out Eric Evans’ iconic 2003 book, Domain-Driven Design: Tackling Complexity in the Heart of Software (Addison-Wesley Professional). In it, he makes the case for a pattern called Bounded Contexts whereby APIs and the underlying applications should be modeled as closely as possible to mirror the data and behavior of your business domain. For example, Eric would call for separate product and pricing APIs, as the two ...