Examining the Construction of Outstanding APIs

API veteran Adam DuVander recently contributed an article over at Stoplight.io detailing “A Real-World Look at Building Great APIs.” This post will probe some of Adam’s key points, examining why his ideas matter to developers and other business stakeholders alike.

What’s the Point of Having an API?

A key benefit to APIs are that they give a connective backbone to otherwise cumbersome stand-alone applications. Adam notes that without this type of focus, teams might “duplicate efforts because there is not a method to communicate that a problem has already been solved elsewhere.”

With an API, the different moving parts of a team are able to move together, glove in hand. The frontend workflow moves collaboratively and in tandem with the backend. Strong, iterative processes grow collaboratively when every part of the team has a birds-eye view of the development process. 

The use of an API also has a stabilizing effect. As Adam DuVander says,  “When an API already exists, teams can build upon others’ work. For example, an API to access a customer’s account details could be useful for a website, a mobile app, and many other consumers. With appropriate permissions controls in place, the same API could even be used in a partner’s application.”

Just as an API empowers a team to work more closely together, a public API delivers immediate visibility to potential partners, as well as opening up internal API development to the possibility of external collaboration. An open API is on an open stage where partnering opportunities are made visible to more companies.

The Lexicon of the API Lifecycle 

Understanding the subtleties of the terminology used under the umbrella term “API development” is essential to an informed conversation about an entire API lifecycle or even just a development phase within the lifecycle. DuVander cautions, “While APIs help you move faster as an organization, that doesn’t mean you should create APIs without a thoughtful process.” 

Looking at the big picture of API development helps lay out the need for a deliberate and balanced approach for the creation of an API. Creation is more than simply the “build” phase. As Gartner defines it, the API development process in fact has three major phases: Design, Build, and Run. Following the development process are another three major phases: Maintain, Support, and Update. Each of these phases is essential to the creation of an API, which is ultimately the sum of its parts (or phases).

As an API moves through its lifecycle, a developer will always refer back to the beginning of API development, with the API design. DuVander advises us, “As you look to update an API, you end up back where any API development should start: with API design.”

An Ideal Development: API Design First

The idea of a “design-second oxymoron” is outlined in this API design guide. The design phase is ground zero for API development: it's at this point that the team will make the bigger picture decisions about both how the API will work and exactly what will make it work. DuVander is a proponent of leading with a genuine team effort: “ Good API development practices will start with a collaborative design phase.”

Be sure to read the next API Design article: How to Auto-Generate gRPC Code Using protoc

Original Article

API Development Demystified