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.
Spec-first or Code-first?
I came across a poll the other day that left me both happy and sad.
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.
Benefits of Going Spec-First
Compared to code-first implementations that generate a spec after the fact, spec-first development has a few advantages:
- Clarity and Consistency - By starting with a detailed spec, developers have a clear understanding of what needs to be built. This eliminates guesswork and ensures consistency in the development process.
- Early Error Detection - Specifying software behaviors and requirements beforehand allows for early identification of potential issues, making the development process less error-prone. You can also build end-to-end tests before writing code. Using tools like Postman, you can create mock servers that return responses based on your spec. This enables you to create testing workflows and swap out mocked endpoints for the real thing as you build.
- Improved Collaboration - A well-laid out specification serves as a common ground for developers, testers, and stakeholders to collaborate effectively. It helps foster discussions and air any concerns before code has begun. Again, Postman offers a collaborative environment on spec design allowing team members to comment and ask questions directly on the specification.
- Seamless Integration - If you're an AWS user, you can use the AWS Open API extensions to quickly go from mock to the real thing, pointing your endpoints directly at AWS services via the specification.
- Time Efficiency - By doing the majority of the planning work up front, you save tons of time during the development, testing, and debugging phases. This leads to faster delivery of high-quality software.
- Meaningful Documentation - Documentation is clearly defined on your paths, schemas, and parameters in an API spec. If you put emphasis on writing clear and meaningful specs, you remove ambiguity and accelerate your integrators.
Getting Started
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.
Happy coding!
Top comments (2)
An interesting approach that takes this idea a step further: write the core sample data, and generate the API spec from there. This provides an even more concise format to flesh out the the API spec and is useful as fixtures for testing as well.
Stripe is the best example of providing simple and concise API documentation.