Transitioning to an API-First Approach: A Month of Insights
Written on
Chapter 1: Embracing the API-First Mindset
Transitioning to an API-first development approach is no small feat. Here’s a glimpse into what you can anticipate in your inaugural month.
For several years, I have been at the helm of teams composed of serverless engineers, working on cutting-edge cloud products. I prided myself on being an innovative manager by implementing an API-first strategy. However, it wasn't until I participated in the Postman customer summit in May that I realized my understanding of API-first was fundamentally flawed. Thus, I decided to take a more committed approach and genuinely embrace API-first product development. Yet, a challenge arose.
API-first development transcends mere technical execution; it represents a profound shift in perspective regarding your product's identity. Is your product primarily the user interface, or does it reside in the API? This critical decision extends beyond the confines of a single engineering team.
Nevertheless, I am determined to instigate change. My mission is to revolutionize how we construct new applications. As of this writing, I find myself roughly a month into this transformative process, and I aim to share insights about my experiences during this initial period and what lies ahead.
Section 1.1: Laying the Groundwork for API-First
For me, the first 30 days of adopting an API-first philosophy were heavily focused on dialogue. Engaging conversations were vital for clarifying what API-first truly entails, discussing the API we were set to develop, and connecting with professionals in the software industry to uncover established API standards.
Building a shared language is crucial for the successful adoption of this approach. Establishing a unified set of objectives, terminology, and comprehension is essential for solidifying the concepts we are about to implement.
Subsection 1.1.1: Aligning Perspectives
The initial discussion regarding API-first took place with senior leadership in my organization. Understanding that this methodology extends beyond the development team, I needed to initiate discussions that would signal a significant shift in our approach.
Adopting an API-first mentality alters the way we perceive our offerings. The focus pivots away from merely delivering a user interface to emphasizing the creation of a robust, user-friendly API that fosters an excellent developer experience.
Convincing product owners to embrace this vision is imperative, as it redefines their long-standing priorities. You must illustrate that treating your API as a product yields several advantages, such as:
- Facilitating easier integration for developers, leading to innovative use cases
- Accelerating delivery thanks to well-defined patterns and reusable standards
- Enhancing product integrity through the ability to write automated tests prior to coding
- Allowing rapid UI updates since all logic resides within the API rather than the frontend
Typically, this list prompts questions like, "What's the catch?" Such inquiries are valid, especially when discussing the potential benefits.
You may need to slow down to accelerate progress.
While everyone yearns to expedite development, merely reacting to requirements is not the path to success with an API-first approach (or any development methodology). Emphasizing definition and design is crucial, which may require a significant mindset shift for some.
Investing time upfront to thoroughly explore every aspect—discussing minor details, behavioral expectations, and data elements—is essential. For me, convincing others to prioritize these discussions and accept the extended timeline was a significant challenge.
Section 1.2: Engaging in Academic Dialogue
When we embarked on this journey a few years back, my entire engineering team, including myself, was new to API design. Consequently, the APIs we developed lacked consistency. Our endpoints varied widely; some supported pagination while others did not, and those that did often implemented it differently.
A key aspect of transitioning to an API-first model involves establishing consistent patterns and governance for other teams, which is also a vital part of enabling successful teams. Therefore, upfront planning is critical.
What HTTP status code should you return for a DELETE request if the entity doesn’t exist? Should you specify minLength and maxLength for request body properties? Does a PUT request create an entity if it doesn't already exist?
There are no definitive answers; your goal is to achieve consistency. As long as you apply the same standards repeatedly, you’ve succeeded.
Expect intense discussions with your team regarding how to standardize practices. Everyone should come prepared to defend their suggestions.
This past month, I was pleasantly surprised by the depth of some discussions. What seemed like straightforward questions often turned into 45-minute conversations and small research projects. We explored why different companies adopt specific practices, leading to rich, academic conversations about the merits of particular patterns.
This process encourages you to critically assess why you're selecting certain best practices. What benefits do they offer to API consumers that alternative implementations do not? Establishing governance rules requires thorough justification for your decisions.
Chapter 2: No Coding in the Initial Phase
Amidst the discussions and technical decision-making, don't expect to write any code during the first month.
Keep in mind that the initial two phases of API-first development—definition and design—are non-coding stages. Gather your team to define the API’s features and explicitly outline what is not included.
Iterate on the design continually, refining it until it aligns with your vision.
While coding may be on hold, writing is not. These phases emphasize the importance of drafting a specification document. Consider utilizing Open API Specification and collaboration tools like Postman to create your initial spec.
Creating this specification involves defining request and response bodies, determining HTTP status codes, and organizing your endpoints to craft an intuitive workflow that addresses business challenges. Utilize your newly established best practices to evaluate your choices and make adjustments early on.
The Following Steps
I remain in the design phase. Although we’ve had extensive discussions regarding business processes and features, we are still iterating on the API structure. This process requires time. You are investing in your API's future, so hastily concluding the design is one of the worst decisions you can make.
The next 30 days hold uncertainties. While I cannot predict the specifics, I anticipate several outcomes:
- Completing the initial design document for the API
- Engaging more groups to promote an API-first mindset
- Initiating end-to-end automated testing
- Creating architectural diagrams
- Coding some endpoints
The first two tasks will wrap up my initial 30-day objectives. Promoting API-first concepts will be an ongoing endeavor within our organization, necessitating continual education to ensure everyone grasps the advantages and disadvantages of our approach.
Building Automation Tests Before Coding
The beauty of API-first development, Open API Specifications (OAS), and tools like Postman lies in their testing capabilities. Once the specification is finalized, QA or automation engineers can commence building end-to-end workflows.
The documentation should be comprehensive, offering a clear pathway for understanding which endpoints to call and what data to submit to fulfill business processes. If gaps remain, further work is required in the definition and design phases.
With Postman, you can create a mock server that returns responses as defined in your OAS, allowing for immediate testing. You can interact with endpoints that yield expected responses, enabling you to develop test suites that connect requests in a cohesive business process.
As developers complete the actual endpoints, you can replace the mock server with the real API. Your tests should remain unchanged, consistently asserting that responses return in the correct format and type.
If switching from a mock to a real endpoint causes tests to fail, it indicates a potential issue with the API implementation. This early detection of bugs is invaluable in the development process.
This fundamentally redefines test-driven development!
Crafting Architectural Diagrams
Once the definition and design stages conclude, implementation begins. However, it's crucial first to create architectural diagrams to represent your work.
Proper API design encompasses two phases: schema design and architectural design. Thus far, we’ve concentrated on schema design, which involves endpoints, request and response shapes, status codes, and how they interconnect—elements that consumers will utilize during integration.
Conversely, architectural design focuses on ensuring your application is reliable, scalable, and maintainable. An API that is well-documented but non-functional is as ineffective as one lacking documentation.
If you're unfamiliar with architecture diagrams, don't worry! Everyone starts somewhere. The key to effective architectural diagrams is to narrate a story. Identify your audience, choose the most suitable diagram type, and convey your message clearly.
Conclusion: The Journey Ahead
API-first development represents not only a technical shift but also an organizational transformation. A significant aspect of this journey is ensuring that all stakeholders agree on its benefits—a task that can prove challenging.
Begin with a small group to gain their support, then progressively expand to larger audiences. Expect resistance, particularly from those who feel their product focus is shifting away from the UI.
Persistence is key. Articulate the advantages of intentional design and prioritizing developer experience. While it may take time to instill this understanding, the rewards are well worth the effort.
One of the goals of API-first development is to achieve fully functional automated tests before the API is even created. Strive to integrate automation engineers into the initial design phase, as they are your first consumers.
Remember to uphold development best practices during your API-first transition. Just because you've invested significant time in design doesn't mean you can rush into coding. Thoughtful architectural design remains paramount.
The more confidence you gain in the business process, the more likely your engineers will feel empowered to "just write it" without hesitation. Mitigating this risk early on, coupled with architectural diagrams and programming discussions, ensures that an API-first approach emphasizes meticulous detail at every stage of development.
If you're embarking on an API-first journey, I wish you the best. My experience thus far has been an exciting adventure, one I wouldn't trade for anything.
Happy coding!