Many application developers are API builders in one way or another. Whether they are building APIs for 3rd party integrators, user interfaces, or as part of a platform engineering team, we have significanttly more exposure to APIs than we realize.
As a consumer of an API, I hate it when documentation isn’t clear or a breaking change is introduced. It makes me feel like I’m not a valued consumer of the API. When developer experience is disregarded in lieu of getting functionality out the door or for the convenience of the developers building the API, I immediately lose confidence in the producer.
The other day I was trying to build an integration with the Twitter/X API. I found the developer portal and followed some links to the dev docs, a public Postman workspace, and sample code. Sounds like a great experience, right?
Unfortunately, the dev docs were unclear and overly wordy, the Postman workspace hadn’t been maintained for a year, and the sample code used an old version of the API that was no longer supported. I went from happy to disappointed to frustrated to rage quite in a matter of a few minutes.
It’s clear that Twitter doesn’t prioritize their API for integrators. After my rage quit, I completely abandoned the integration I wanted to build. I have no trust the API works or will continue to work over time. And now I’m here, making sure that you - my fellow API developers - don’t make the same mistakes.
I came across a poll the other day that left me both happy and sad.
When building an API do you write the spec before you code or do you generate it from your code?— Rich Buggy (@richdevelops) September 25, 2023
I’m happy to see that the majority of voters are building their APIs spec-first. I’m sad to see it wasn’t a 100% vote for it. There are still many of us out there who are writing code and generating a spec from that.
The good news is that pretty much everybody sees the value of an Open API Spec. It’s hard to argue against their importance. But too many developers don’t see the importance of starting with them. Focus on creating meaningful contracts and endpoints. Think about what would make your integrators delighted when they use your API. Do this before you code.
By going API-first you’re making a commitment to your consumers. You’re committing to focusing on intentionality. You’ll plan out the experience ahead of time. You’re going to make sure everything is properly documented the instant a new feature is available. Breaking changes are going to be a thing of the past.
I like to use a hyperbolic example when comparing code-first and spec-first development.
Imagine you’re building a house. Would you rather the crew draft a blueprint ahead of time and build to that spec? Or would you rather them go off and build your house then create a blueprint of what they built when they were done?
Both blueprints would be an accurate representation of your house, but chances are the house that had the blueuprints ahead of time will make more sense. It will flow better. It will actually be what you want. The other house will shelter you and provide you a home, but it might not be the best it could have been.
Compared to code-first implementations that generate a spec after the fact, spec-first development has a few advantages:
I admit I’m taking a pretty firm stance on this topic. Hundreds, if not thousands, of developers have found success by going code-first. It’s not wrong to do, it’s just not the best way 😝
All jokes aside, building the API spec before writing the first line of code was pivotal in my journey to build the best developer experience I could. It was a tough change and a difficult sell to my organization but we powered through and came out with a tremendous respect for DX and API design. You learn how to make things easier for your consumers and oftentimes make it easier to implement as well.
If you’re looking to get started with spec-first development, try writing one from scratch. I highly recommend the Swagger editor, which is an online tool that renders your specs as you type them. Get a feel for what it’s like to define your data transfer schemas up front and learn how you can reuse schemas across multiple endpoints.
This is a completely different way to write code but I strongly feel like it’s the best way for long term maintainability and viability of your APIs. If you have any questions, feel free to reach out to me and we can talk about it.