If you ask 10 developers to describe how an API should look and function, you’ll get at least 10 different answers. The development team working on your APIs may have more opinions about API style than members! The one point they’re likely to agree on is that within any single API, what matters is consistency. Clashing values can add up to clashing styles, so choosing one to align on is important.
If you dig a little deeper, you’ll find developers all acknowledge there’s never going to be a singular definition of good API style and design. For better or worse, every API will inevitably have different needs and require different tradeoffs. On the one hand, this is a problem – we’re all well aware of the perils of decision paralysis, and of the mess that results when you put off making hard choices.
On the other hand, variety can be a blessing that enables creativity. Your development teams are not locked into a single way of doing things and can work to find the best solution for your unique product.
Building an API that lasts requires committing to an API style. If developers are going to adopt your API, they need to quickly grasp its potential and put it into action without a lot of headaches – that relies on consistency in all parts of your API program. If integrations will grow over time, your API needs to evolve predictably and sustainably along with them.
How do you know if your API has style? A quick way to evaluate is to look for three things:
- Is your API designed around consistent models for consumers and use cases?
- Do you have complete OpenAPI coverage?
- Are you using an automated linter or a compliance tool across your APIs?
Let’s look at each of these three API style factors in more depth below.
High-Quality User Models Help Deliver Style Consistently
When we talk about API models, we’re not talking about data models and CRUD functionality. The data model approach is all about what you can do with data using the API. Rather, the models we care about are user models. An API with a consistent, high-quality style will focus on what people – your users– will do with your data in the real world.
In other words, we recommend approaching API design with a focus on developer experience; this approach is usually called a design-first approach. Ask yourself:
- Who will use your API?
- What are your users’ desired outcomes?
- What steps will your users need to achieve their desired outcomes?
If you can answer these questions with clarity and show it in your API product, then you are on your way to a well-defined API style.
Fundamentally, this is a UX approach. You have a limited set of well-defined personas, each with clear objectives. You want to develop and test user flows with these personas in mind, ensuring that they can achieve their goals with a clear path through your API. Just as a consumer-facing product defines its style based on its customers, you define your API style based on the developers and use cases you will serve.
Prism supports the design and mocking process, allowing you to develop high-quality user models and envision use cases.
OpenAPI Standards Simplify API Adoption
The main reason to prioritize a consistent style for your API is that it makes it easier for developers to adopt and integrate. The faster potential consumers can test your products in action, and the more readily they’re able to scale their integrations, the better it is for your long-term growth.
Adopting industry-standard practices serves the same goal. Most developers have become familiar with OpenAPI Specification, a standard for describing REST APIs that has the added convenience of automatically integrating with many API tools. OpenAPI offers a common structure with a lot of flexibility to suit your needs and your users’ needs. Using a familiar standard shortens user’s on-ramp and smooths out bumps in the journey. Developers know how to get started with an OpenAPI-compliant product, and they know where to find what they need. Pave an easier road for developers to adopt your API and they’ll appreciate your style.
It’s worth considering how adopting OpenAPI Specification looks from a public perspective, too. The developer community is increasingly pushing for greater transparency and progressive standards around data freedom and disclosure. Setting up OpenAPI conveys a commitment to the values of the community. Your API style is a signal to developers about who you are as a company. Choosing to consistently follow industry standards demonstrates your respect for your users.
Ultimately, following an industry standard makes it easier for you to become an industry standard. Elements is a tool from Stoplight that makes generating great documentation from your OpenAPI files easy.
Automated Tools Apply Style Efficiently
You want your API to be highly predictable, simple to build with, and efficient to create and maintain. Predictability, modular code, and efficiency are closely tied. Style governance addresses all of these areas together. Good governance goes beyond a list of rules to include structures that enforce the rules, ideally with as little human effort as possible.
If you really want your API style guidelines to be in effect consistently across all your API offerings, automate as much of your governance as you can. Many different developers will touch your API code and automated tooling is the only way to ensure your vision becomes reality in the same style across all of them.
Just as we talked about improving the developer experience for your API consumers, this is about the developer experience for the people building your API. If you make it easy for them to comply with guidelines and integrate linting into their workflow as an automated step, you will see more consistent results and happier developers.
The reality is that developers come from many different backgrounds and therefore have adopted different styles that occasionally conflict. Automated linting tools like Stoplight Spectral, let you set your standards in one authoritative place while ensuring they’re enforced everywhere in your codebase. Integrated within the Stoplight Platform, Spectral helps keep your entire API program consistent.
API Style Resources
In a follow-up post, we’ll share additional resources to get you thinking about the details of your API style, as well as examples of different style guides. What really matters is committing to a style and applying it everywhere. There isn’t likely to be one absolute “best” style guide out there, so focus on consistency, transparency, and ease of use.
Even if your team won’t be coming to a consensus about the perfect style any time soon, getting started toward a consistent, developer-friendly style can happen quickly with a few smart choices.
For more style advice, you can check out our style guide best practices and think about how you’re currently addressing key areas for style guide coverage.
