What is Your API IQ?

What is Your API IQ?

In the blogosphere, there is much opinion and controversy over the “right” way to do APIs. The primary schism lies in the perspective of the job they are trying to do. We hear statements like “REST is dead,” “GraphQL is the new standard for APIs,” “OData is the best way to REST,” “REST is the only true API,” etc. And there is truth in the perspective of each of these statements. However, these statements are certainly not universal. They are situational and they are solving differing problems. What’s missing is a standardized definition of an API IQ.

The first thing we need to agree on is that interfaces (today, most interfaces are referred to as APIs) are created by producers for consumers. The convenience, clarity or ease of creating the interface is not the primary concern. The concerns should be oriented to the consumer. What does the consumer know about the implementation, the systems, the business processes, and the organization? And the other critical question, “Is there more than one consumer?”

The answers to these questions will dictate where your focus should be in the creation of your interface to get your most valuable results.

We created the below API Interface Quadrant to help developers understand where their focus should be when they are creating an interface and why. The framework is rather simple. And there are certainly more grey areas between each category that we could include. However, this simple illustration will get you thinking about the most crucial concerns.

What is Your API IQ?

The Framework

An Explanation of the Axes

“Number of Consumers” and “Familiarity and Proximity” are not the only two considerations when building your interface. We chose these two axes because these metrics will have the most impact on how you design and build your interface to create great consumer experiences.

Number of Consumers

The number of consumers is a critical driver in how you should build your interface. It may be practical to explain the structure and behavior of your interface to a single consumer, but this simple approach quickly loses value when we add more than one consumer. In my experience, on-boarding a consumer to an interface is very time-consuming. And not just anyone’s time. Typically it’s your most valuable developers. And by the time you onboard your second interface consumer, you would have been better off focusing on making the interface self-evident so that all future consumers can utilize the interface in a self-service manner.

Familiarity and Proximity

Familiarity

Familiarity with the Implementation

Since the beginning of component development, the primary job of the interface has been to simplify the use of and hide the complexity of the implementation. The amount of work you need to do to hide this complexity is dependent upon the familiarity of the interface consumer with the implementation.

If they are very familiar with the implementation, then you will be able to take some shortcuts. You will not have to translate language that is set by the database or system, and you will not have to restructure or orient things so that the consumer will be able to derive context. This significantly lowers the bar.

Now not all implementation familiarity is equal. Some interface consumers may be very familiar with the technical implementation details where others may just be familiar with structure and language.

If the intended consumers of your interface are not familiar with your implementation, then you should consider transforming the structure and language to align more with the consumers’ understanding. If there is more than one consumer, then your consumer-oriented design considerations will have a significant payback in the effort.

Proximity

Working Proximity to the Implementation Team

The computer scientist, Mel Conway, has taught us that proximity dictates design. This is largely due to human nature. And communication and collaboration are more effective, due to planned and unplanned interactions when teams operate in working proximity. The less interactions an implementation team has with the interface consumer, the less communications and the harder it will be for them to answer questions and successfully utilize your interface.

API Interface Quadrants

Quadrant 1: Team

Only one consumer; high familiarity with the implementation; working proximity

Language
COULD use language surfaced directly from the implementation.
COULD ensure the contract language uses consumer-oriented terms and descriptions.

Contract
SHOULD use a contract interface that is ideal for the Consumer.
SHOULD adhere to best practice implementation of the contract.
SHOULD organize the contract structure in a way that is logical to the Consumer.

Behavior
SHOULD ensure that the interface returns minimum expected behavioral information.

Documentation
MUST provide just enough documentation for the Consumer to successfully integrate.
SHOULD document the behaviors as well as the contract structure and language sufficient for the Consumer.

Infrastructure
MUST ensure your system’s capacity meets the demand needs of your consumer.
Latency SHOULD meet your Consumers’ requirements.
Availability SHOULD meet your Consumers’ requirements.

Quadrant 2: Integration

Only one consumer; low or no familiarity with the implementation; no proximity

Language
SHOULD use language that is clear and simple to understand for your Consumer.
COULD ensure the contract language uses consumer-oriented terms and descriptions.

Contract
MUST use a contract interface that is ideal for the Consumer.
SHOULD adhere to best practice implementation of the contract.
SHOULD organize the contract structure in a way that is logical to the Consumer.

Behavior
SHOULD ensure that the interface returns minimum expected behavioral information.

Documentation
MUST provide just enough documentation for the Consumer to successfully integrate.
SHOULD document the behaviors as well as the contract structure and language sufficient for the Consumer.

Infrastructure
MUST ensure your systems capacity meets the demand needs of your consumer.
Latency SHOULD meet your Consumers requirements.
Availability SHOULD meet your Consumers requirements.

Quadrant 3: Domain

More than one consumer; high familiarity with the implementation; working proximity

Language
SHOULD use language that is clear and understandable to the teams with implementation understanding.

Contract
MUST use a contract interface that is ideal for the Consumer.
SHOULD adhere to best practice, if possible, to create opportunity for expanded use.
SHOULD organize the contract structure in a way that is logical to the Consumer.

Behavior
MUST ensure that your Interface returns expected results. In the case of REST use common RFC compliant response codes and patterns.
MUST ensure that errors return self-evident messages that let the Consumer know what clearly went wrong and how to correct it.

Documentation
SHOULD provide self-service documentation that allows consumers to discover and understand your interface.
SHOULD thoroughly document the behaviors as well as the contract structure and language.

Infrastructure
Since there may be many Consumers and we don’t know their consumption needs, you SHOULD ensure that your systems capacity is elastically scalable.
SHOULD ensure that your interface is performant.
MUST ensure that your interface is highly available.

Quadrant 4: Product

More than one consumer; low or no familiarity with the implementation; no proximity

Language
You MUST use language that is clear and simple to understand for your Consumer.
Your contract language MUST use consumer-oriented terms and descriptions.

Contract
MUST use a standard contract that is current and common in the development community.
MUST adhere to best-practice implementation of the contract.
MUST organize the contract structure in a way that is logical to the Consumer.

Behavior
MUST ensure that your Interface returns expected results. In the case of REST use common RFC compliant response codes and patterns.
MUST ensure that errors return self-evident messages that let the Consumer know what clearly went wrong and how to correct it.

Documentation
MUST provide self-service documentation that allows consumers to discover and understand your interface.
MUST thoroughly document the behaviors as well as the contract structure and language.

Infrastructure
Since there may be many Consumers and we don’t know their consumption needs, you SHOULD ensure that your systems capacity is elastically scalable.
SHOULD ensure that your interface is performant.
MUST ensure that your interface is highly available.

Lou Powell

Lou Powell

EVP, Solutions & Innovation