A cornerstone of API development, OpenAPI offers a standardized format to define, design, and document APIs. Born out as open-source and embraced by tech giants like Google, Microsoft, and IBM, OpenAPI isn’t just a specification—it’s a shift toward interoperability, transparency, and developer empowerment. In this article, Lorna Mitchell, a leading voice in API tooling and VP of Developer Experience at Redocly, sheds light on best practices, pitfalls, and how teams fully harness OpenAPI’s potential.
Edited Transcription
OpenAPI is an open standard for describing HTTP APIs in a machine-readable format. Developers can use OpenAPI to define the structure, endpoints, parameters, responses, and error codes of APIs. As the popularity of OpenAPI suggests, using an open standard for designing APIs has appealing perks. “The idea is because everybody is describing their APIs in this standard way, you can then pick and mix all the tooling that you use all the way through your API lifecycle, all the way through those pipelines, because we have this standard interoperability format,” explains Lorna Mitchell, VP of developer experience at Redocly and member of the Technical Steering Committee for OpenAPI. As she explains, given OpenAPI is open source, “anybody can write tooling” while knowing that OpenAPI standard ensures “that all your tools work nicely together, and your APIs can be used by everybody.”
In this way, the OpenAPI specification can be used to automatically produce code libraries or SDKs that developers can use to interact with the API in their preferred programming language. These libraries handle the low-level details of making HTTP requests, parsing responses, and managing errors, allowing developers to focus on building their applications instead. “The future is very bright in that space,” Lorna affirms, “the landscape for things like overlays, things like adding transform steps and enriching an existing OpenAPI document, those things have really improved over time as well.”
Standardization in API design
For designing APIs, “OpenAPI is a very rich source that encompasses data and metadata that is used by all of the different tooling, including your server backend, your client generation, your code stuff, probably your API gateways.” Hence, given how much it is hardwired into the very logic of APIs, Lorna understands that “the value you get from OpenAPI is hugely related to how much you input into it in the design process.”
Design-first development, defined by Lorna, consists of “having a review process as things are designed and before they are implemented” to ensure better product consistency and usability. At this stage, she emphasizes, “it’s your opportunity to check that all of your API is consistent with the rest of your API.” As such, even the involvement of stakeholders like tech writers and UX experts during the design phase can robust the API’s intuitiveness and capability to meet the needs of its users.
Similarly, during the API development process, it is also possible to gather valuable feedback. To this end, Lorna suggests “sharing the open API description with everybody” alongside a mock server so developers can get their hands on the product and experiment with it.
In this regard, to enhance developers’ manageability, API specifications should avoid a monolithic structure. As Lorna notes, “You publish a single open API description file and it’s available as one file to download from your documentation, but you’re probably not evolving and maintaining it like that.” Instead, she recommends a modular approach, that is, breaking the OpenAPI description into smaller, more manageable pieces. This allows reviewers to focus on specific sections. “Most people will use a split structure so that every path, every schema, and so on, each is in its own file,” Lorna explains. Similarly, GitHub issues and discussions provide a structured framework for tracking changes and gathering input.
For launching, being transparent about the API’s stage in the OpenAPI description and related documentation “will help people understand where they’re at,” says Lorna. Simultaneously, manual onboarding, she says, will provide a “manual touch” in which “you know who’s onboarding and you have contact details for them so that you can reach out to your users if things are changing while you’re in that sort of early access stage.”
API analytics
While analytics are not part of the OpenAPI specification itself, there are practical approaches to gathering and making the most of API usage data. Lorna finds two main approaches for collecting API analytics. The first is instrumenting the backend, which involves adding custom tracking to the API server, similar to how you would track metrics for any server-side application. The second is using an API gateway or proxy, which can handle analytics automatically without requiring changes to the backend code. Lorna notes these are “both good options” and says that the choice between these approaches ultimately comes down to “whatever your engineering team most fancies trying.”
To interpret analytics, these should answer pre-established key questions, such as understanding usage patterns, error rates, or performance bottlenecks, “that will help you sort of work backward as to whether you have the data or you need to make more arrangements to collect it.” Likewise, to be valuable, analytics should present data “more actively in your sort of key metrics, dashboards, and setup.”
Documenting APIs
OpenAPI can be used as well to automate API documentation by parsing the OpenAPI file and creating documentation that includes details about endpoints, parameters, request/response formats, and authentication methods.
Once general availability is achieved, making API documentation publicly available after reaching General Availability (GA) demands a holistic approach to developer experience. This way, documentation is not limited to reference docs. Equally valuable are welcoming introductions, tutorials, and task-based guides that “really welcome people in, help them understand what this is and what it does,” says Lorna. Likewise, documentation can take the form of creating an entry point for developers, such as a developer portal or API showcase, that explains the API’s purpose, pricing, and licensing terms upfront.
Lorna also recommends having “real task-based guides” that cover “what do you see people doing with your API” and “the different steps” to achieve specific tasks with it: “even if you don’t cover every exact use case, your developers will pick the pieces they need and build their own masterpiece.” In this regard, as for tooling, Lorna recommends taking a look at the recently released Arazzo Specification (formerly known as Workflows), which describes sequences of API calls. She explains that this standard can help improve task-based documentation by showing how multiple API calls work together to accomplish a goal: “It doesn’t work to have just a single API call; It’s always going to be this sequence and they tie together.”
Additionally, the feedback the support team can gather from the customer base and where they get stuck is ground for new documentation: “There will always be edge cases and the reference docs, you cannot manage without them, but showing, walking people through the most common use cases can unlock a lot of users to be successful.”
The bottom line
Redoc is Redocly’s open-source tool for generating interactive API reference documentation from OpenAPI specifications. For teams seeking end-to-end API management, Redocly offers Realm, a comprehensive suite of tools designed to support API development and documentation across all stages of the API lifecycle.
To explore the OpenAPI standard further, visit the OpenAPI GitHub repository for the latest specification updates and contributions, or check the OpenAPI Initiative website to learn about ongoing projects, community events, and ways to participate in shaping the future of API standards.
For insights into Lorna’s work, visit her personal blog for articles on APIs, open source, and developer experience. She actively contributes to open-source projects, including OpenAPI tooling, on her GitHub profile. Lorna is also a board member at OpenUK, a nonprofit advocating for open technology adoption in the UK.
