The basis of famous Zachman’s framework lies in “perspectives” (row) and “focusses” (columns) of the grid, that are used to describe information technology. “Perspectives” provide levels of granularity in problem domain whereas “focus” is about primitive interrogatives (What, When, Why, How, Who, Where). Once we familiarize ourselves with the framework, we realize that this is not limited to big IT problems in enterprises. It can be applied to any engineering problem in information technology (or outside). A problem well defined is problem half solved, and this framework provides a structured way to articulate it.

I have outlined how primitive interrogatives can be leveraged as a tool for API analysis and design, and how these enable us to ask right questions in the early phases of API development. These also help us think about the constraints in the problem domain. Even though the intent here is not to strictly follow or illustrate usage of Zachman’s framework, the details are around row # 3…ish, the “Architect Perspective”.

So let us get started. For an API to exist, we at least need two parties that need to exchange information. API can be generalized further, as we add more parties to the mix.

In Zachman’s terms:

Who

Who identifies the “actors”. This could be a “mobile application” that needs data from a single “enterprise data store” (or multiple aggregated stores), or a “partner” requesting quotation from a “business application” owned by the enterprise.

Example:

An e-commerce mobile application, used by customers, needs to retrieve “delivery addresses” from customer data store. “Mobile” application and “customer data store” are the actors exchanging information in this case. Mobile application prefers not to communicate using SOAP based xml, so that becomes a constraint.

Why

Why do these need to talk to each other? Does the caller needs information, or it provides information, or both? Is it one-way communication, two ways, or a call back?

Example:

The context of communication could be multiple. In our example, retrieval of address book could be for a “selection” of a delivery address for the purchase, or to “verify” that certain address does exist in the address book, and add if it does not. Can service be generic enough to accommodate all these use cases? These questions help us understand the problem.

When

When do these applications communicate? When and what triggers the communication and how often.

Example:

The likelihood of alternate flow (“add new address”) as part of address retrieval, in example use case being invoked is more when new purchases are being made by the customers. This require holding “purchase” use case, jump to “add new address” and then continue with purchase completion. How do we couple such use cases? Can newly created address be updated asynchronously in “address book” as part of purchase? These are some of the poking questions, which need to be satisfied as part of analysis and design exercise.

What

What is the content and context of the information exchange? What is the sensitivity of content being transmitted?

Example:

What does “address” object in our example entails? Can it accommodate address fields variations, if catering to multiple countries? What type of data it is going to be (SOAP, JSON, etc.). Is there a need to have one-time-use address, which need not be stored in the “address book” but is still required for shipment and tracking purpose?

Where

Where are application located. In relation to each other, are these located locally, remotely, on-premise, cloud or both? And so on. What implications could the location of application have on API led integration of applications? Within the API itself, there are variations. What do those mean to API design. An API wrapping a CICS transaction require different development strategy than building one ground up on micro-service architecture.

Example:

In our case, consumer is mobile applications connecting to a data source. We need to think about hops in between Mobile and actual data source. These could include CDN, Firewall, API gateway (if any) and similar intermediaries. What value each hop is adding and how it would contribute to our API design. What is our caching strategy?

How

How in theory (as per framework) is about the “process” definition. But in this case, if all other areas above were part of “analysis”, I consider “How” as “design” (and not actually the “process”). We define the actual API specification, selection of tools and technologies, frameworks, addressing of cross cutting concerns and so on.

Example:

We, say, chose open API specification (previously swagger), to define our API. We implement API on Microservices based architecture using Spring Boot, use NoSQL database and host our service on AWS as part of our enterprise infrastructure.

I hope this helps in analysis and design of APIs.