Business-First API Design and Development

I spend a lot of time thinking about API-first design and development, where you craft an OpenAPI definition, mock, document, and iterate upon the design of an API before you develop it. An API-first approach to the design and development of an API comes with a number of benefits for a team and the resulting API, but it is something that there can still be a lot of resistance to when it comes to gaining adoption across an organization. Some teams will be open to learning how to design their APIs using OpenAPI before they ever write any code, but others will resist for a variety of reasons, some founded, and others un-founded. I am always looking for ways that I can improve upon how I talk about API-first, but also how I make it better meet the needs of folks on the ground of API operations. My latest attempt in this area I am calling business-first API-first design and development—-it is a boring name, but it is what I’ll start with and hopefully polish over time.

Beginning with an API-First Design Approach

My approach to API-first has gotten pretty polished through repeated demos with Postman customers and analysts. I have been able to distill down a pretty straightforward approach to designing an API using OpenAPI in a collaborative way down to a handful of steps. Providing with a variety of hands-on API-first examples that exist within public API workspaces, which leverage these API-first design building blocks.

Workspace - Designate a specific workspace for each bounded context which an API is being developed, ensuring that all stakeholders are able to find not just the artifacts for each API, but also all of the operations around the API. Ensuring that there is always a dedicated workspace to find everything you need to produce or consume an API.
Team - Invite individuals to be part of the team who will have access to the workspace, artifacts, and other elements of the design, development, and operations of any API. Ensuring all stakeholders have access to the work going on around each API, and is part of the conversation occurring around the design and development that is going on.
OpenAPI - The machine readable API specification is the center of not just the API design process, but ultimately the entire lifecycle for the API. Every API begins with an OpenAPI definition that provides the details of the request and response surface area for each API path. Providing a machine and human readable contract for what an API does.
Comments - The ability to have a conversation about each OpenAPI, as well as each individual parts of an OpenAPI. Allowing team members to be able to discuss each path, parameter, header, body, response, schema, example, and any other moving part of the API being defined. Keeping the conversation thread associated with each API contract.
Mock - Using the OpenAPI for each API to generate a mock representation of an API from the examples provided for each request and response within the OpenAPI. Allowing for each API path to have its behavior simulated as expected in production, but done in a way that doesn’t require writing any code and can be rapidly iterated upon using examples.
Documentation - Publishing human readable documentation that is generated from the OpenAPI being designed, ensuring there is always an HTML representation for stakeholders to use to understand what an API does without having to look through the technical details of the OpenAPI being designed, helping provide documentation throughout the process.
Iterate - Using the workspace, team members can iterate on the design of the API using the OpenAPI contract, using the mock server as a constant representation fo how the API will behave, and the documentation a manual of what consumers can do with an API. Repeating and iterating upon the design until it meets the needs of everyone involved.
Testing - Once you have the contract for an API representing what all stakeholders are looking for you can write tests for each of the API paths to ensure that they always operate as expected. Ensuring that once an API moves forward through each stage of development it always meets the business requirements established as part of the API-first process.

I have a product, as well as restaurant API-first workspaces that I use regularly as part of customer and analyst calls, as well as part of my webinars, workshops, and other events that I do. I am very happy with my current approach to API-first because it provides a hands-on example of how you can design an API before you actually develop it. However, I admit that it takes a certain amount of awareness around RESTful API design patters before you can hit the ground running, and you have to be introduced to each of the steps involved in an API-first concept before you will become proficient in putting my approach to work. While this approach isn’t going anywhere when it comes to my API development toolbox, I am looking for ways in which I can make more relevant to how organizations are thinking about the value APIs deliver, over just it being about API-first.

Evolving to a Business-First API Design Approach

Working at Postman you spend a lot of time thinking about API consumption as well as producing APIs. This reality has pushed me to think about the role that Postman as an API client plays in shifting the API-first process, and has me thinking about how I can turn my approach above on it’s head a little bit, making it easier to implement without having to necessary have RESTful API design skills, while also bringing things closer to the business side of things. Here are the steps in what I am calling a business-first API-first approach to designing an API, ultimately ending up in the same place, but rather than beginning with an OpenAPI, that is the final contract you produce once done with the design process.

Workspace - Designate a specific workspace for each bounded context which an API is being developed, ensuring that all stakeholders are able to find not just the artifacts for each API, but also all of the operations around the API. Ensuring that there is always a dedicated workspace to find everything you need to produce or consume an API.
Team - Invite individuals to be part of the team who will have access to the workspace, artifacts, and other elements of the design, development, and operations of any API. Ensuring all stakeholders have access to the work going on around each API, and is part of the conversation occurring around the design and development that is happening.
Workflows - Create a simple collection with just a title and description of the business workflows you are looking to enable with the development of an API, grouping them by folders, and adding individual requests for each step of the workflow, trying to be as precise as possible about each step of a workflow, beginning with descriptions, and then more details.
Examples - Providing an example of what each request and response should be for each step of the process, ensuring that each step delivers what is needed to meet business needs. Ensuring that each step in a workflow has a real world example of what should be expected when it comes to a request and response.
Comments - Team members can common on the details of a business workflow and each of the individual steps. Having an active conversation about each step, as well as the paths, parameters, headers, bodies, and response details. Providing an iterative feedback loop about how to translate business requirements into an actually functioning API.
Mock - Generating a mock server from each workflow collection, turning each of the requests and examples into a functioning static mock representation of what will happen when you run each step of the workflow. Allowing for each step of the workflow to have a hands-on representation of what is expected when an API actually runs in production.
Documentation - Publishing always up to date documentation of the set of business workflow APIs being designed, providing a human readable overview of the workflow APIs being designed, but also details of each step involved. Making sure there is always up to date documentation for the team to reference when trying to understand what is possible.
Iterate - Using the workspace, team members can iterate not he design of the business workflow by adding steps, iterating upon existing steps, modifying examples, and ensuring that an API will do exactly what it should be doing. Ultimately reaching the same goal of an API-first approach, but doing so without starting with a blank OpenAPI canvas.
OpenAPI - Once a business workflow operates as expected an OpenAPI can be generated from the workflow collection, providing the central source of truth for the API being delivered, but using the mocked and documented workflow collection as the representation of the contract. Getting to the same place we did above, but more about business-first.
Testing - Once you have the contract for an API representing what all stakeholders are looking for you can write tests for each of the API paths to ensure that they always operate as expected. Ensuring that once an API moves forward through each stage of development it always meets the business requirements established as part of the API-first process.

With this process you get to the same point as my API-first example above, but instead of having to be OpenAPI literate you can lean on mapping out all of the steps of our business workflow, before diving into the technical details of delivering an API. You are still designing an API before you write code, but it backs off the need to understand OpenAPI-driven API design. You don’t have to be as literate in the details of OpenAPI before you can get to work just fleshing out what is needed to meet business requirements of an API. It feels more aligned with meeting business needs, and less dogmatic about RESTful API design, something I am hoping will resonate with some of the folks I am talking to.

A Collection-Driven Approach to API-First

The inspiration for this approach is born out of the power of Postman as an API client. I am a firm believer in an OpenAPI-driven approach to API design, but I am also a realist when it comes to what folks have the education and bandwidth for on the ground of API operations within most enterprise organizations. Most people I talk to won’t have the time to be properly trained in RESTful API design practices, or the nuances of OpenAPI, but still would benefit from going API-first and developing APIs in a more collaborative way. Teams would still walk away from the process with an OpenAPI contract that can be used to guide API development and publishing to an API gateway as part of the deployment process, but also for more rapid and iterative delivery of simple APIs and API enabled workflows that are closer aligned to business goals. In this approach we aren’t starting with the technical constraints of OpenAPI, we are just starting with the title and description of our workflow, and the title and description of each step of our workflow—until we’ve made it behave as expected.

Next I will create some workspaces dedicated to this approach to designing and developing an API. Then I will work on some demos and recording of my approach, helping me work out some of the rough edges. While I love the elegance of an OpenAPI API-first approach, this approach feels more like what many folks on the ground within enterprise operations would relate with, while still leading them towards a more efficient, collaborative, and OpenAPI driven approach to setting APIs in motion. As I work on iterating this new approach to delivering APIs as part of my API toolbox, I will also work on the name I use to describe this approach. It needs something catchy, but represents a shift from the API-first way of doing things that folks have been hearing about for the last five years. With some retooling I am thinking we can bring on a new batch of folks to an API-first way of doing things by adjusting a few of the steps, and coming up with some new branding and narratives that help them understand the potential.