I recently had the opportunity to meet with Postman executives and other industry leaders in the API space. It was a terrifying, exhilarating, and humbling experience. We talked about everything from developer experience to API lifecycle to API-first development to even the future of the API landscape.
It was awesome.
I make it no secret that I'm passionate about two things: serverless and APIs. To be in the midst of the most passionate API-heads around was invigorating.
When we started having conversations around API-first development, something caught my attention. I have been talking about being API-first for years thinking I was doing it but when we talked about the nuance of implementation, I quickly realized what I thought was a lie.
Ok, not really a lie, but I was under the wrong impression. What I discovered is that you might be under the wrong impression just like I was.
So let's talk about it and figure out if you actually are developing API-first or if you just think you are.
What Is API-First?
I will never explain this as well as Kin Lane from Postman does. He can explain all the aspects of being an API-first company in 13 points.
High-level, API-first means that you prioritize your APIs as your product. You put intentional strategy into their design, implementation, security, and discoverability.
While these traits might sound like obvious components to focus on, it's really the context that is the differentiator.
Traditionally, you'll see companies that put the focus on design, security, discoverability, etc... into the application they are building. Meaning the full stack app they are shipping off to customers. This inherently isn't an issue, but it isn't API-first.
With API-first, the context is your API. It's the mechanism used to manipulate your system. You put your emphasis there so integrators have the same keys to the system as you (with a few exceptions).
API-first is about a mindset shift from building custom applications for your consumers to enabling them to build it themselves.
Take the hassle off of you to create and maintain custom apps. Provide a meaningful developer experience for your consumers and they will flex your system in ways you never expected.
If you think you do this already, so did I. Let's discuss what all this means when it comes to the day-to-day.
What Does That Mean?
When putting API-first development into practice, the detail really surfaces in standard process changes you'll have to make. It's not just the order of events that needs to change, but the effort that goes into structuring the work.
Defining the Work
The first phase of API-first is define. The definition phase of API development involves more than just developers. It involves the business and product units working with development to clearly define the functionality this API is intended to bring.
What business problems are you trying to solve? What data entities are involved? What is the lifecycle of each of these entities?
More detailed questions like should this be a PATCH or a PUT, how should we structure the endpoint format, and how do we handle paging should already be answered questions and defined in your governance model.
If you don't already have a governance model in place, that would be a good place to start. If you don't know where to start on building a governance model, you can use the Postman Open Technologies Governance Rules collection as a foundation.
Governance rules are meant to be iterated on. So find what you like, make modifications, and address anything new that comes up. The important part is that you start somewhere.
Approaching the work in this manner is the same whether you are creating a brand new API from scratch or adding functionality to an existing one. Getting the group together to discuss the business objectives and clearly define the problem area is always step one.
Splitting Up Stories
When I first started with my version of API-first, I was under the impression that it meant all I had to do was work on the endpoint stories first.
API-first does not mean simply doing your API stories before your UI stories
In fact, it is totally viable to work on the UI and API implementation at the same time with API-first development.
Your first set of stories is building out the API spec, which includes endpoints, schemas, and examples for your requests and responses. Once those are completed, you can create a mock server which will return fake data in the expected format.
With this in mind, your UI development can begin while you start the real implementation of your API. Remember, with this development approach you treat your API as your product. Any UI you build on top of it is a value-add.
Testing and Monitoring
Resiliency and robustness are key success indicators in API development. To test these components, your APIs should have a variety of different tests that stress them in different ways.
- Contract tests - verify the API accepts and returns the correct schema in the request and response
- Performance tests - makes sure your API returns a response in the expected amount of time
- Security tests - determines if your API has the correct access control around data and endpoints
- End-to-end tests - run workflows through the system to make sure different business objectives can be completed
Not only should you have each of these tests for your API, but you also need to have a way to make sure they aren't throwing errors. Use any sort of APM like DataDog, New Relic, and even Postman to monitor the success rates of your tests and notify the proper team when something stops working.
Including automated API tests as part of your definition of done is an indicator you are doing API-first right.
If you aren't running these tests as part of your development cycle, you need to start. Contract tests and performance tests can be dynamically generated. But for end-to-end tests, you need to put some conscious manual effort into making those run real-world scenarios.
The better you can automate the scenarios your consumers are running, the higher likelihood you won't push out a breaking change.
Making Your API Discoverable
When I was managing a cloud-native dev team, we would complete the work on a new API and move onto the next story. Other teams around my company would have no idea there was a new API, and in the off chance they found out about it, they would have no idea how to find it and integrate with it.
Heck, even developers on my team would have a hard time finding details on an API.
This is because we weren't making our APIs discoverable.
Imagine you're selling your house and your realtor lists it on online on their website. They don't put a sign in your yard or advertise it on social media. Chances are your house isn't going to sell in any reasonable amount of time. This is because it isn't discoverable.
How are buyers supposed to find your house? Do they have to know to look at your realtor's website? That's not going to happen.
The same thing applies when you're building an API. You need to surface it an a place people know where to look then advertise the crap out of it.
If people have to ask you where to find the documentation for your API or what APIs you have available, consider that a red flag that you aren't doing a great job with discoverability.
Postman has both a public network and a private network to make it easy for you to share your APIs externally and internally.
Conclusion
API-first means treating your API as your product.
To do that, your focus and emphasis has to change. You aren't driving design decisions based on where you think a user should click. Instead, you're thinking about how you can easily let integrators chain requests together to complete a business scenario.
Work across the organization to design your API spec in a meaningful way. Iterate the design until you're happy with it. Don't start writing code until the spec is complete.
Put renewed attention on monitoring capabilities. Change your definition of done. Don't accept anything that needs to be manually tested every time a change is made. Automate the tests and notify the team when it breaks.
Let the world know what you've done. Put your APIs in a network that allows them to be easily discovered. Don't rely on word of mouth and tribal knowledge when your API is done. Your dev team doesn't scale. They can't work on new APIs and evangelize the APIs they already completed.
This development approach feels like it turns standard development on its head. And that's a good thing.
Disruption drives innovation.
By pivoting your organization to focus on APIs and developer experience, you open the doors to things you never thought possible. People are creative. If you give them the keys to your API, they will make it do things you never thought imaginable. Which is what we're all here for.
Happy coding!
Top comments (2)
Hey Allen,
Developer Relations person from Postman here. Great article, enjoyed reading it very much, not only because it mentions Postman. =D
Your dedication to API-First is a great asset, and I wondered if you'd heard about our community program Postman Supernovas?
Hey Jan, thank you! I have heard about the program, we can talk about it offline if you'd like