‘Developer Experience’ is a loaded term. For the sake of this blog post, we will define it as: ‘All interactions between a developer and the API’. This includes: discovery, documentation, ease of use, flexibility, etc. DX doesn’t only focus on the technical nature of APIs but also encompasses the empathetic efforts done by API providers to properly understand the needs and pain points of the API consumers.
API design first in essence
Traditional ‘code first’ development prioritizes implementation over usability, leaving a greater risk for poor adoption by consumers. API Design first tries to achieve the opposite. By adopting this approach, API providers focus on designing a clear, intuitive and easy-to-use interface before doing any implementation. This is achieved by building the API specification and data models based on the needs of the consumer. Frequent feedback loops between provider and consumer guarantee that the right API is being built.
Advantages of API design first
- Improved usability: By focusing on the API design, API consumers will have an easier time to understand the interface, effectively reducing time to market on digital applications.
- Collaboration mindset: Collaboration between developers, product owners and designers happens early in the development lifecycle. This joint effort ensures that everyone’s valuable perspectives are being considered.
- Lower development costs: Spotting potential issues and inefficiencies early will avoid costly debugging and rework.
- Developer satisfaction: Happy developer, happy life.
- Innovation over integration: By reducing the cognitive load of developers, we can allow them to focus on innovation over integration.
A few best practices for API design
- Simplicity over everything: API Providers should strive to avoid unnecessary complexity in the API. This will keep the learning curve low and will allow for improved adoption.
- Document beyond the specification: Provide comprehensive and easily accessible documentation that includes clear examples, tutorials, and use cases.
- Consistency and Standards: Establish consistency in your design practices. Introduce naming conventions and predictable error-handling mechanisms across your entire API landscape.
- Involve your developers: Actively engage with your API consumers. Address their needs and listen to feedback.
Conclusion
Essentially, APIs shouldn’t be reduced to their technical capability. There is still a developer on the other side of your API (for now). Building a good developer experience is all about building the right tools for the people doing the job, and building them the right way.
When we compare APIs to something in the real world, one analogy that’s used frequently is the waiters in a restaurant. So when introducing DX into the equation, we can safely say: No matter how good the food is, if the waiters are not there with the customer’s needs in mind, it’s going to be a poor experience overall.