To become useful, the API architecture needs to be put into practice. This is why this book covers an API methodology for design and development. An API methodology provides practical guidelines and explains how to develop an API architecture into an API that consumers love.

The methodology we propose is an outside-in approach, which also incorporates ideas of contract first design and simulation. In this methodology, the contract is expressed in the form of an API description. In each step of the methodology, an API description is either created, refined or used — the API description is the red thread connecting all the steps of the methodology.

Let’s start with an overview of the phases in this API methodology. Each phase of this methodology consists of a creative part and a verification part. During the creative part an artifact is crafted, during the verification part early feedback on the artifact is collected. In each phase along the design and development journey, we elicit feedback from the consumers. This is how feedback can be collected as early as possible, when changes to the API are still possible, relatively simple and can be implemented at low cost.

This methodology is meant to be used iteratively. There are small iterations, which are triggered by the verification part of the same phase. There are also big iterations, which are triggered by one of the later verification phases and require going back to the creative part of an earlier phase. Keep in mind, that in an iterative and agile approach, not all information and requirements about the constructed artifact are present in the beginning, but new and more detailed information is gathered in each iteration.

The API methodology consists of the following phases:

  • Domain analysis
  • Architectural design
  • Prototyping
  • Building API software for production
  • Publishing the API

To learn more about putting APIs into practice, check out my new book on API architecture and API methodology.

How to put API Architecture into Practice?

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at, is the author of several books on APIs, and regularly speaks at technology conferences.