For the past few years, I’ve been leading teams of serverless engineers to build some innovative new cloud products.

I thought I was the hip, forward-thinking manager by saying we were going to do API-first development. We ran with it for years but it wasn’t until I attended the Postman customer summit in May that I realized what I thought was API-first……wasn’t. At all.

So I decided to make an adjustment. I opted to go all-in and actually build products API-first. Except there was a problem.

API-first is not only for development teams.

It is a complete mindset shift of what your product is. Is your product the UI or is it the API? This is a decision that veers way outside of a single engineering team.

But I am nothing if not persistent. I was (and still am) set on making a change. So I set out on a mission. I’m going to change how we build new applications.

At the time of this post, I’m about a month into the process. We’re going to talk about what went into that first 30 days and what to expect out of the next 30.

Starting Off With API-First

For me, the first 30 days of API-first was a lot of talking. Talking to get people to understand what API-first means, talking about the API we were about to build, talking to people in the software industry to discover their API norms, etc…

This is exactly what we want because in order for something to take off and be truly understood, you have to build a ubiquitous language. Establishing a common set of goals, verbiage, and understanding will cement the ideas you are about to put forward.

Getting on the Same Page

The first conversation I had about API-first was with the senior leaders at my organization. Knowing that this methodology doesn’t stop at the development team, I had to start planting seeds that things were about to change.

When you go API-first, your mentality changes about what you’re selling. You are no longer solely focused on delivering a user interface to your customers. Your primary focus shifts to providing them with a rock solid, intuitive API with a great developer experience.

So I had to sell that. Product owners need to be on board with that vision because you’re changing what they’ve put all their focus on for ages. You need to convince them that treating your API like a product is the best way to go because it:

• Allows integrators to easily pick up and build with the product, leading to innovate new use cases via your customers
• Speeds up delivery because of strongly defined patterns and reusable standards
• Strengthens the integrity of the product because automated tests can be written before the code
• Enables lightning fast UI updates because all logic is kept in the API instead of the front end

Providing this list of reasons usually leads to someone asking “what’s the catch”, which is a totally fair question when talking about the benefits.

You must move slower to move faster.

Everyone wants to move fast. Hear the requirements and build. But that’s not how you’re going to find success with API-first (or long-term success with any development style). Definition and design become of utmost importance and that might be a radical change for some people.

Spending the time up front to completely walk through end-to-end, discussing minor details, expectations on behavior, and data elements become an up-front exercise. For me, this was one of the hardest pieces to sell: putting additional emphasis up front and feeling like we’re extending the timeline by having many discussions on what we want.

Have Intense Academic Discussions

When we first got started a few years ago, my entire engineering team, myself included, were brand new into API design. As a result, the APIs we built are all over the place. We don’t have established norms and consumers of the API know it. For example, some endpoints offer paging while others don’t. The ones that do, all do it differently.

A big part of going API-first is establishing repeatable patterns and governance for other teams (it’s also a big part of enablement teams as well). So up-front planning comes in here as well.

What response code do you return on a DELETE where the entity is not found? Do you need to set minLength and maxLength on your request body properties? Does a PUT create an entity if it doesn’t exist?

There is no right or wrong answer. Your goal is to become consistent. As long as you do it the same way over and over and over again, you’ve made the right decision.

With this in mind, be prepared to have intense discussions with your team on how things should be done. Everyone should bring their “A game” and be ready to justify the reasons why they think their way needs to be the standard.

This was a pleasant surprise for me over the last month. Some of the “easy” questions ended up turning into 45 minute discussions and a small research project. We wanted to understand why other companies do things in a specific way, which led to some digging and additional research.

This turns into discussions to talk about the findings, which leads to high quality academic conversation on why a specific pattern should or shouldn’t be implemented.

All this to say, think about why you’re using a specific best practice. What does it offer to the consumer of your API that another implementation wouldn’t? You’re setting up your governance rules, be prepared to justify your decisions.

No Writing Any Code

Between all the conversations you’ll be having with different departments and the technical decision making you’ll be doing, don’t expect to write any code in the first 30 days.

Remember, the first two phases in API-first development are definition and design. These two phases do not involve any coding. Get everyone in a room and talk about the definition of the API. What are the features you want? What do you explicitly not want?.

Iterate on the design as you work. Hone what you have until it feels right and matches the plan.

API producer lifecycle, source: Postman

Just because you’re not coding doesn’t mean you won’t be writing anything. These two early phases focus on writing the specification document. Consider using Open API Specification and a collaboration tool like Postman to build your initial spec.

Building the spec involves designing request and response body definitions, determining response codes, and figuring out how to structure your endpoints to build an intuitive workflow that satisfies the business problem. Use your new best practices to vet your decisions and make adjustments early.

The Next Phase

I’m still in the design phase. We’ve had many discussions on business processes and feature sets, but we aren’t done iterating how the API should be structured. This process takes time. You’re investing in the future of your API, so rushing to get the design done is one of the worst decisions you can make.

The next 30 days are, of course, a mystery. I can’t guarantee what is going to happen, but I know what should happen.

• Finish the initial design document for the API
• Talk to more groups and evangelize an API-first mentality
• Begin end-to-end automation tests
• Draw some architecture diagrams
• Code some endpoints

The first two points are wrapping up the tasks from my first 30 days. Talking to groups about API-first will never be done. This type of development will continue to spread through the company, so we will need to continue educating to make sure everyone understands the pros and cons of what we are doing.

Building Automation Tests Before Coding

One of the beautiful things about API-first development, Open API Specifications (OAS), and collaboration tools like Postman is the testing capabilities it enables. Once the specification is complete, QAs or automation engineers can start building end-to-end workflows.

The documentation should be complete and provide an easy way to figure out which endpoints to call and what data to pass in to them to complete a business process. If it’s not, that means you have more work to do in the definition and design phases.

With a tool like Postman, you can create a mock server that will return the responses defined in your OAS so you can begin testing immediately. You can hit endpoints that return your expected responses, allowing you to build out test suites that chain together requests in a given business process.

As the developers complete endpoints, you can swap out your mock server for the real thing. Your tests don’t need to change, they should already be written and asserting that values come back in the right shape and type.

If you swap out a mock endpoint for a real endpoint and your tests break, that likely means the implementation of the API is incorrect. This means you found a bug as early as possible in the development process.

This gives a whole new meaning to test driven development!

Draw Some Architecture Diagrams

After the definition and design phases are done, it’s time to start implementing. But first, you need to draw some architecture diagrams to represent the work.

There are two phases when it comes to proper API design: schema design and architectural design.

What we’ve already spent a decent amount of time on so far is schema design. The endpoints, shape of the request and responses, status codes, and how they chain together are all part of the schema. It’s what your consumers will digest as part of their integration.

But the other part is your part. It’s the architectural design. Making sure your application is reliable, scalable, and easy to maintain is just as important as the schema design. An API that is well documented but doesn’t work is just as good as an API with no documentation.

If you’re new to architecture diagrams, don’t worry! Everyone has to start somewhere. The most important part when building an architecture diagram is telling a story. Figure out your audience, determine the best type of diagram to build, then tell your story.

Conclusion

API-first development is just as much an organizational change as it is a development change. A big part of the journey to becoming API-first is to make sure everyone agrees it is the right way to go - which is a task easier said than done.

Start with a small group of people and get their buy-in. Then go to a larger group, then larger still. There will be some people who argue against it, especially when they hear that you don’t want to treat the UI as their product anymore.

Be persistent. Explain the benefits of putting intentional design and focus on developer experience. It might take time to get that through, but the tradeoffs are absolutely worth it.

One goal of API-first development is to have fully functional automated tests before your API is even written. Try to enhance your process over time to include the automation engineer in the initial design. After all, they are your first consumer.

Remember that you still need to follow development best practices when going API-first. Just because you spent all that time on the design up front doesn’t mean you can dive in and write the code. It still needs careful architectural design. This can be an easy trap to fall into because by the time you get to writing code, everyone should feel like a business expert.

The more confidence you have in the business process, the more confident your engineers will have they can “just write it” and throw caution to the wind. Catch that early and enrich development with architecture diagrams and programming discussions. Going API-first puts more attention to detail in all phases of development.

If you are going API-first, good luck on your journey. It has been an adventure for me so far and I wouldn’t trade it for anything.

Happy coding!