Leah R. Tucker - Designing a Future-proof API Program

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 8 April. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Leah R. Tucker

API architect, technical writer, and platform engineer at {your}APIs

Leah's presentation (video recording)



Leah's slides



“A brand is simply trust”, as Steve Jobs said it. Our APIs are the extension of our brand.

The goal of our API program should be to help our supply chains create the most interoperable building blocks for this brand:

  1. An API team is a (part of a) supply chain, it is a system of people, activities, and resources used to move a product or service from a supplier to customers.

  2. APIs, produced by different API teams (of the same company), are the key building blocks supposed to serve developers’ needs and expectations of interoperability.

  3. And interoperability is the capability of a product or system to interact and function with other products or systems, which is what we want from our APIs to do.

In order to achieve this, supply chains have to be provided with a cohesive set of guiding principles.

Disintermediation is the removal of intermediaries from a supply chain to reduce liability and costs.

Who is in charge of consistency when designing APIs? Who is in charge of brand loyalty?

The decentralized approach to data architecture in disintermediated supply chains:

  • Different API teams use different data model conventions.
  • It results in too many custom building blocks that overcomplicates work with our APIs.
  • Results in data discrepancy.

If no consistent set of data modules were applied across supply chains, app developers wind-up stuck in data silos with no way to scale-up.

The community approach to data architecture:

  • Creating new APIs rapidly by building from centralized data libraries we end up with directly responsible supply chains.
  • Allows the consistency that app developers are looking for.

The standard approach to API documentation:

  • Provide your supply chains with standard interfaces–templates–for the API specifications.
  • Allows your teams to produce a consistent approach for customers consuming APIs on the devportal.

An API Design Guide:

  • Provide your supply chains with a design guide to document your conventions.
  • Case conventions for the request/response, product name, collection/resource name, error handling, etc.

If a consistent set of data models, rules, and policies were applied across our supply chains, app developers no longer need to write code for conversions or complex workarounds.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.