I am fleshing out ideas from a couple of recent conversations around API life cycle religion and philosophy. We’ve made our way through several lofty ideologies around how you should or shouldn’t do APIs, and next up in the queue is API specification first, or API spec first development. I like the phrase. I like it a lot. However, I am afraid if we aren’t being precise in what we mean by it we might be sacrificing a more meaningful usage of it for delivering a certain class of API that is meant for reuse. This is another one of my pedantic API definition stories, but since it is meant to help me use my words better in these conversations I am having, and secondarily for a wider reading here on the blog, you are going to have to bear with me as I work through my feels about API spec first development (should there be any dashes in there?)
To help guide me in my work, I am using my API reference implementation “Union Fashion” as a foundation for this narrative. I’ve been calling what I am doing with Union Fashion API-first, but honestly I’m just looking to build out the best reference implementation that I can showing how to do APIs thoughtfully—I am not trying be prescriptive about there being one way do APIs, or one phrase to describe it. It just doesn’t exist. However, I do like peeling back the layers on the onion until I cry. When it comes to Union Fashion I might be agreeable to calling what we are doing API spec first development, if we are using it in two possible ways. Let’s use the Union Fashion products API to help break things down and see if we can’t help flesh out what we mean by API spec first development.
The Product API Began With Three Specifications
When I first started development of the Union Fashion product API it began with a specification, an empty OpenAPI in my local IDE. It began with an API specificatio--we are off to a good start right? Maybe this is API spec first development! Facing my OpenAPI I now needed to define what my “product” schema would be before I get to work on the actual API. When it comes to common everyday objects I always begin the journey with Schema.org, another specification, which in this case I leverage the products object. To quantify the Schema.org product object as my product object I use JSON Schema, which fits nicely with OpenAPI, which has also adopted the open source schema specification to define the underlying objects used as part of the request and responses of APIs it is used to define. I have just started defining and designing my products API and I’ve used three separate specifications:
- OpenAPI - We will use version 3.0.3 of the OpenAPI specification as the central truth for the Union Fashion product API.
- Schema.org - We are using the Schema.org product object as the underlying specification for our Union Fashion product.
- JSON Schema - We are using JSON Schema to define our product object, and referencing it within our OpenAPI definition.
Ok, I have an product object, and I begin to define each path for creating, reading, updating, and deleting objects in my OpenAPI definition, wiring up the request and response objects to reference my Schema.org compliant product object which is defined as JSON Schema. Ok, I have used three specifications to create the definition for my API, which allows me to the potentially mock, document, share, and collaborate around the evolution of my products API. Is that API spec first development because I am ALWAYS researching, considering, and building with common specifications, or is it APII spec first development because I am creating a spec for my API? If it is the former I can get behind it, if it is the latter than I think it loses meaning, and potentially takes away from the development of reusable API specifications which I will talk about shortly.
At Union Fashion I am not developing a specification. I might be developing an API using specifications, but really I could get pretty wild about the design of my API moving forward and negate much of the benefit of the specs that I am using. I am using OpenAPI, JSON Schema, and Schema.org to create a definition for the Union Fashion API, but I am not creating a specification. I am just using specifications to jumpstart my API, and maybe to shape my API, but I am not developing an API specification. Or am I? If I leverage other standards, and open source my specification and some or all of the tooling around it, maybe I could consider my Union Fashion API to actually be a specification, resulting in this being…wait for it—api specification development.
Union Fashion Product API as a Specification
Not all APIs are “open APIs” designed for reuse. There are few APIs that provide you with the definition of the API, as well as server, client, documentation, and other building blocks to deploy that API in compliance with a specification. This type of API development is ideal because it allows API providers to deploy many different APIs which all follow the same API specification (ie. PSD2 or FHIR APIs). This is where we want to be for all major industries. We want a wealth of API specifications for many different industries all defined using OpenAPI, JSON Schema, and Schema.org. However, this adds an entirely new dimension to API spec first development as well as what I’d consider to be API spec development. Imagine being API spec first at a bank and to kick things off developing your API you don’t just choose OpenAPI, JSON Schema, and Schema.org, you also choose PSD2 for the specification of your API, ensuring your bank is in compliance with EU regulation and is reusable in a variety of tooling. I can really get behind this type of API spec first development, especially when there are a wealth of API specifications that have been developed and are available like PSD2 and FHIR.
Confusion Around What is the API Specification
Ok, phew. I worked my way across this spectrum not to just be pedantic about a simple phrase. I want to just make sure we are in alignment on what we mean when we say API spec first development or API spec development, because they feed each other. If you Google API spec first development, the majority of the posts say "specification" as a way of expressing what is produced first as part of the development of your API. You aren’t. It is unlikely that you are producing a reusable specification. You might be. Don’t get me wrong. If you are, then use it. I just want to make sure we aren’t just loosely throwing it own there because if you are using OpenAPI and JSON Schema (two specs) to develop your API, and what you build isn’t reusable as a pattern, then you didn’t produce an API specification, you produced and API definition using API specifications. I put this out there because I want to be honest about my intent behind each Union Fashion API, fully admitting that some of my APIs may some day rise to the level of a specification, but it is likely that most the APIs I’ll be developing, no matter how many specifications I use, and how well defined my process is, will never be a specification for use in someone elses API.
So I think that API spec first development has its place. I also think we can do a better job of using this term. I think specifications are important. I just don’t think everything we do rises to the occasion of being API spec first development, and especially not API spec development, so I just want to be careful. Let’s definitely look at using API specification at the beginning of any API journey. Let’s definitely discover, reuse, and contribute to API specifications like PSD2, FHIR, Open Referral, Open311, and other open source API specifications that are defined using OpenAPI and JSON Schema. Let’s be more cautious if we are building momentum around marketing, branding, and storytelling that uses API spec first development if the intent behind the API isn’t designed for reuse, because in this middle ground the outcome of development isn’t going to be a spec. Ok, I think I have my head wrapped around the spectrum of what I mean by API spec first development. I feel a little more equipped to partake in lofty conversation about the term without flip flopping around. It helps to keep the words I use in my storytelling and conversations grounded, otherwise this stuff gets pretty unwieldy pretty quickly.
