As I often say, “APIs are forever”, so API design is an important step. Once you release an API for others to use, you should never make breaking changes as this can disrupt the applications that depend on it. As we wrote about previously, we need a versioning strategy to ensure we take the proper precautions to avoid doing harm to our API consumers.
Between the time when you design your API and the point in which you release it to consumers, there is a huge opportunity to iterate on your API design to make it better. Too often, we rush through this process without taking advantage of the opportunity to learn and improve on our API design prior to release. Let’s explore more about how we can iterate on our API design prior to releasing it.
Take a design-first approach
Capabilities enable someone to achieve something they previously were not able. Features are the individual steps and/or mechanisms that allow them to achieve those outcomes. If you are too focused on the API design before you know what your audience is trying to achieve, your API product will fall short.
I recommend a design-first approach that identifies the capabilities to be delivered, then designing the API to meet those capabilities. Once designed, the API is then delivered quickly across multiple releases.
Seek fast feedback cycles
The longer your API takes to get into the hands of developers, the longer your feedback loop. However, a rushed API often requires changes that will force consumers to adapt quickly or jump to a competitor. How do API product teams balance the need for speed and great design? Decrease the feedback loop.
Even though an API lasts forever, you can encourage early feedback from internal teams, key stakeholders, and partners willing to work with you during the pre-release phase of your API. Feedback at this stage is critical, as it will expose wrong assumptions and add real world testing prior to releasing your API to a broad audience.
By incorporating feedback cycles into your API before its release, you increase the chances that your API will meet the needs of your audience. Additionally, it gives your internal teams time to work through the final details of releasing your API, including comprehensive documentation and executing a complete testing strategy.
Putting it all together
To accelerate the delivery process and create a tightly-focused feedback loop, consider the following:
- Build an API delivery team using cross-functional resources: developers, QA, technical writers, and other roles necessary to deliver the API end-to-end.
- Utilise API definition formats, such as the OpenAPI Specification, to communicate the API design to everyone involved.
- Take advantage of mocking tools that allow for early experimentation with your OpenAPI definition before coding starts. A point in time when the cost of API design change is much lower.
- Keep stakeholders involved early and often through shared design documentation and mockups to verify understanding and intent.
- Deliver the API continuously, rather than all-at-once, using stakeholder feedback to prioritize the delivery schedule based on their needs.
Remember: Once released, it is difficult to change an API design. Use this accelerated delivery process to expedite your learning and stakeholder feedback early on, before your API is officially released.
