Mike Mackrory is a guest contributor for the Runscope blog. If you're interested in sharing your knowledge with our readers, we would love to have you! Please fill out this short form and we'll get in touch with you.
In part one of this series, we talked about the OpenAPI framework and the concept of API-First development. In this second and final part, I’d like to demonstrate how this framework and these principles can be applied in the day-to-day functioning of a technology organization to increase velocity and improve the effectiveness of your development activities.
I’ll start by describing the problems we faced as an organization and how we used these principles to not only solve those problems but also improve how we were able to develop applications. As with any process, our implementation had some hiccups, but we learned valuable lessons. Through sharing these lessons, I’m hopeful that I can enable more people to be successful if they decide to implement an API-First method in their organizations.
The Landscape and the Problem
I’m privileged to work with some very accomplished and talented engineers. We’d assembled different teams and assigned Scrum masters and product owners. We’d embraced the concept of microservices and Agile methodologies, and we were ready to go.
The goal was a scalable commerce platform with each team owning microservices for their domain. It was going to be an open-qsource-style nirvana.
The problem was that each domain was dependent on services owned by other teams, and even when you assemble great people, engineers tend to embrace a tribal mindset. In the best environments, projects can get caught in logjams of dependencies and requirements.
Begin with the End in Mind
When your goal is a microservice platform, what you’re looking for is a collection of highly interactive applications. These interactions can also be called APIs, and in the environment, the API is the keystone which facilitates cooperation.
API documentation, therefore, becomes critical, and the earlier it is created, the more useful it becomes. No time is better than right at the beginning of the project. API design-first was the plan, but the reality didn’t always reflect that goal. APIs were poorly documented, and often teams treated them as work-in-progress. If I had to point to the number one source of problems when we began, it was inadequate attention to detail in the APIs and failure to treat the API documentation as a contract.
API Design-First
Start every project by developing comprehensive API documentation, and you’ll save yourself a great deal of stress over time. Since we began our project, we’ve developed API standards based on domain-driven design. Focus your efforts on those APIs which expose functionality between teams first.
Designing your API is an exercise in requirement-gathering and determination of business requirements. Involve the business, product owners, engineers and subject matter experts in this effort. The resulting documentation should be agreed upon by all parties and published for everyone in the organization before writing a single line of code.
The use of a standard specification like the OpenAPI Specification (OAS) will make this process easier and enhance adoption throughout your organization.
Development
Development starts when the API has been agreed upon and publicized. At this point, the API is a contract, and any changes require special consideration. We’ll talk more about how to deal with changes shortly.
The benefit of having API documentation available before development is that your inputs and outputs are clearly defined. The person responsible for creating stories or tasks for development efforts can reference the documentation to help explain the requirements.
The API document only defines the interactions between your application and the rest of the organization, or the outside world. You can implement logic, update functionality and optimize processes, and as long as you abide by the input and output defined by the API contract, you can be confident that your changes won’t affect other teams in your organization.
Dealing with Changes
Changes happen. It would be rare for all requirements to be identified during the development of the API documents, and even if they were, in our highly connected world, changes would happen at some point. How you manage changes will make or break the process for the organization.
We started by requiring teams to announce changes when they happened. The problem with microservices is that you don’t always know every service that has your application as a dependency, and even if you do, the chance of someone missing the memo is highly likely.
We implemented versioning to help manage this better. Requiring a new version of the API when breaking changes are introduced helps manage the change process. Versioning allows teams dependent on your application the time to transition to the new API before the old version is deprecated.
Admittedly, as domains became more established and the platform stabilized, this has become far easier to manage.
A Process of Continual Improvement
We’ve been following these principles for a few years now, and it’s improved the development process exponentially. It hasn’t always been rainbows and unicorns, and we aren’t at that stage yet, but we’re moving towards it. We’re continually learning and adopting new standards as we find better processes, but making the API documentation the foundation of everything we do has been a game-changer.