The world of cloud-native systems depends upon many constructs, protocols, standards, structures and software languages, but if there is one entity within this complete universe that now enjoys more prevalence than most, it is the API.
The use of Application Programming Interfaces (APIs) has mushroomed with the rise of the modern web and cloud over the last quarter-century. Often described in layperson’s terms as the glue that bonds different applications together inside the firmament of cloud, APIs also connect lower-level application components together and form a bond to higher levels Operating System (OS) structures, when that communications conduit is needed.
Written to a defined and required syntax, APIs have a prescribed style that they must adhere to. We have already discussed what makes a good API on IDG Connect here, but over and above building APIs with solid ‘call rate’ limiting controls, should we also be thinking about the stylistic approach behind how we create these technologies.
What style means to an API
If we were to ask a dozen different developers to define how a good, cool and perhaps nicely styled API should function, we might get two dozen different answers. But despite these differing opinions, organisations need consistency in their API design style in order to be able to work with the differing needs of future designers as a company might expand or scale.
To an API, style means being able to go out in public wearing the same coat now and in five years’ time.
While there is no foolproof solution, there are some helpful guidelines to building an API design that will stay effective for years. Jason Harmon, CTO at API platform company Stoplight, believes in automating style governance by using an automated ‘linter’ (a compliance tool used to flag programming errors, bugs, suspicious constructs… or indeed stylistic errors) as the first step to success.
Harmon says that we’ve seen this whole scenario play out before.
“During the first User eXperience (UX) age in the late 90s, the front-end developer community realized that UX really mattered to users and was a way to enhance visibility and even brand affinity. Fast forward to today, the developer experience movement is modelling that same path; make the API development process easier on developers, while ensuring that the APIs being created are more useful to end users. Here are a few tips for styling effective APIs,” he said.
The Stoplight team advocate a trio of approaches, the sum of which they suggest can come together to prove IT departments with an appreciation of API styling that will look good this season and for seasons to come.
Tip #1: Consistency
“Consistency is the primary difference in experience between a bunch of APIs and something that feels like one cohesive platform. Implementing style guidelines into an API strategy makes consistency and standardization a no brainer. API style guides are easily consumable instructions for all relevant information that a development team will need to create or work with APIs,” explained Harmon.
Tip #2: Design-First
Drawing from its own client base experience, Stoplight’s second pillar of API style comes down to adopting design-first approach. This oft-overused term does actually means something in API terms. It is based on the idea that APIs are products that should be created in an organised, thoughtful and intentional way.
When building APIs, it’s important that it’s not just for the original developers, but also the end-users and community that will potentially interact with them. With this approach in mind, the team suggest that the very foundation of each API is rooted in designing for a broader global audience.
Tip #3: Get automation tooling
Harmon obviously advocates the use of his own firm’s product to provide automation tooling for API style fabulousness. In this case the product is called Spectral, an open source linting tool (remember linters and linting from above?) that allows users to create style guides for specifications including OpenAPI/AsyncAPI/RAML descriptions, Kubernetes configurations and GitHub actions.
It operationalises style guides (i.e. makes them workable and usable in the workplace) so they can be easily shared with other development teams to bring uniformity to all API programs.
A close confidente of Stoplight’s Harmon is freelance technical writer Janet Wagner. Toledo, Ohio-based Wagner echoes the need to style and form in API creation and lays down what she estimates are the six key form factors that should denote API style.
“Every API style guide [should] include architectural style, API description format, naming conventions, error handling, authentication & authorization, plus also 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,” wrote Wagner, in a September 2021 blog.
Just like a good coat or a fine pair of shoes then, APIs do have a style about them and good styling and care does lend itself towards creating a product that will last through this season and into the next.
