Public style guides are available for Professional and Enterprise workspaces. Simply log into your workspace, click on the Governance tab, and look for Public Style Guides, then enable the rules you want to use.
Does anyone remember user experience (UX) coming of age in the late 90s? To summarize, the front-end developer community realized that UX really mattered to users and was a way to enhance visibility and even brand affinity. Over a relatively short period of time, the UX design discipline grew, matured, and developed automated tools to improve UX in a consistent, efficient, and scalable manner.
Fast forward to today, it would be practically irresponsible to say that you’re designing a comprehensive user experience across multiple teams without some UX expertise and tools. In more mature scenarios, automation around Design Systems would be an expected tool to drive UX design consistency.
So, I’d like to think that Developer Experience is in the early stages of a similar period of growth and maturation, and API developers are adopting design-first approaches to refocus on end-user and developer needs. Developer Experience as a design discipline manifests itself strongly in API Design. APIs are often the most developer-centric product, and if done well, are obvious and relatively self-describing to leverage. API ‘design-first’ really just expresses that we should design APIs with the broader platform in mind…before we build them.
If the movement had to be described with a single word, it would be empathy. As with any design discipline, it’s a required attribute for building a successful consumer experience. It’s about making the API development process easier on developers while ensuring that the API products being created are more useful to end-users – and consistency is a big part of human-centered API development. If you imagine that 1000 developers using your API could reduce the code to consume that API by 10 lines through consistent patterns, you’ve just saved the developer world 10k lines of useless code, and 1000 developers some measure of their valuable time.
Empathy is also the primary reason why the first API style guides were written. Here’s a quick primer on why style guides exist, what they do, and how they’re evolving to deliver a level of automation and scalability that is a game-changer for many companies.
Why do we need style guides?
Consistency is the primary difference in experience between a bunch of APIs and something that feels like one platform. But how does an organization achieve consistency while APIs are concurrently being developed by a number of different developers, API teams, or partner organizations?
Our CEO at Stoplight, Steve Rodda, describes APIs as technology ambassadors – essentially the digital representation of a company or brand – and it makes sense. Branding is about defining a look and feel that represents a company and then consistently reinforcing it across all communication channels and platforms. Likewise, to successfully define an API platform, a similar level of consistency is required.
The first style guides were developed between 2013 and 2015 to set expectations for look and feel (aka DX) for API development teams. The need for design consistency was apparent from the outset of API platform development, and early efforts by Paypal (and yours truly) and Heroku resulted in some of the first style guides from successful programs being shared publicly. In general, I would say that these tools strived to present the basics of good API design and documentation so the style guides could be useful to both the organizations’ core (internal) user groups as well as the broader community of API developers.
The Public Sector soon caught on, too, as evidenced by the White House publishing an API standard for government agencies. In recent years, many major tech companies including Google, Cisco, and Microsoft have released their API style guides to the public.
These efforts at platform consistency began maturing the process of transforming collections of APIs into recognizable API platforms and provided an example for other organizations to follow as they set out to define their API program.
What do style guides do?
At the most basic level, companies adopt style guides to ensure consistency by implementing a set of design rules. My peer Janet Wagner published a great list of six key things that should be included in every API style guide, including architectural style, API description format, naming conventions, error handling, authentication and authorization, and versioning. When style guides proactively address all of these aspects of API design, there is much less wiggle room for inconsistency to creep in and a much better chance of developing a cohesive and unified API platform.
Spectral — The Evolution of API Style Guides
While style guides are essential for creating a strong API platform, there’s a downside: Manually writing them and enforcing their use can be a challenging, time-consuming process for both your API development team(s) and for those tasked with ensuring compliance. The historical examples of API style guides were frequently tomes of rules that were hard to read, remember, and put into practice.
The good news is that, as was the case with UX in the 90s, and later with UX design systems, development technology is maturing and new automated systems are now available to help. Linting tools, for example, define a set of rules to verify if an API complies with a given API style, and they are among the most effective automation technologies for managing APIs.
Over the past few years, there have been a variety of attempts to create linters in the OpenAPI tooling community. As recent as 2019, there were a number of options, as well documented by NordicAPIs. However since then, we’ve seen Spectral’s adoption spread across the OpenAPI community very quickly, and it’s emerging as the leader for OpenAPI linters.
Spectral is Stoplight’s open-source linting tool for JSON/YAML, and it allows users to create style guides for specifications including OpenAPI/AsyncAPI/RAML descriptions, Kubernetes configurations, and GitHub actions (or any other JSON/YAML structured data). Basically, Spectral operationalizes style guides so they can be easily shared with other development teams to bring consistency and uniformity to API programs of any size. (If you’re curious about how this might work for a large organization, check out how Adidas did it.)
In addition to synchronizing API design teams, Spectral also enables the people who are managing your company’s API program to focus their efforts to operationalize a style guide on the most meaningful questions, such as
- Why does this API exist?
- Who is it serving?
- Are the terms being used customer-centric?
Spectral automates the painful bits and affords people time to focus on the big-picture questions that will really drive adoption instead of being bogged down in little details that aren’t directly focused on the concerns of customers and API users.
While Spectral is a relatively new arrival, it is making a big splash in the open-source API development community because it finally provides a realistic option for automating consistency across growing API programs.
Thinking in UX terms, Spectral is the API equivalent of Google’s Material Design platform, relative to the impact it’s making across the industry. Our product designer, Noor Ahmad, outlines it best.
“Google’s Material Design is one of the best tools out there that clearly explains style guides and design systems which mirrors exactly what we are doing with Stoplight’s version of style guides,” Noor shared with me.
Let’s break that down. Essentially, design style guides equate to written guidelines explaining the standardization and the “how-to-use” guidelines for things like typography, layouts, color, and spacing methods. On the other hand, Stoplight style guides are the equivalent of written guidelines explaining the “how-to-use” guidelines for things like API paths, parameters, and headers.
Now, Noor explains that there is not quite a platform out there today that helps users quickly and easily generate a design system the way we’re doing it at Stoplight. You could get relatively close with options such as Figma, Axure, and Adobe XD which all allow you to create components, store them in a library section, and drag-and-drop them into your design file. I’m excited to share more on our API design libraries feature in the coming months, but I think the user community will be quite pleased with the experience when it’s launched.
And in the meantime, we’re looking forward to a variety of updates to our Style Guides feature in the coming weeks that will be available to Stoplight users on pro and above plans. As I mentioned at the start of this, Style Guides have come a long way in a few short years and they are the best way to implement consistency in your API program moving forward.
If you’re a CTO or technology leader investing in APIs, and you’re looking for tools to create some consistency in your existing program, Spectral is the tool you need. You don’t have to be an expert to make impactful changes in a short period of time.
I’m the CTO of Stoplight, and I blog about APIs and how we’re helping countless companies establish productive API programs. I hope you’ll join the conversation.
