A developer (dev) portal provides a space for creating and maintaining high-quality API developer documentation. Dev portals are fast becoming the industry standard for presenting this type of content.
At Swrve, we are moving towards a programmable customer experience (CX), which has extended our API offerings to our customers. As part of this change, we have taken a fresh approach to our API documentation by creating a dedicated Swrve dev portal. We have created our portal using the Stoplight API design tool.
In this piece, I’m going to provide an overview of Swrve and our previous documentation architecture, the reasons for choosing Stoplight as our API documentation tool, the positive and negative outcomes from using this tool along with some best practices, and how we plan to move forward with Stoplight and our overall documentation architecture.
The 2021 SmartBear State of Software Quality survey found that accurate and detailed documentation was considered the second most important characteristic in an API.
A well-written, structured dev portal provides the necessary information required to configure and manage developer interactions with your APIs. Technical communicators provide high value to dev portals through the creation of detailed documents, such as API overview and tutorial documentation.
The SmartBear survey also provided a breakdown of the most important factors when using an API. These included examples, status, and errors, authentication, error messages, HTTP requests, parameters, getting started guides, methods, code samples, tutorials, etc.
A dev portal provides a means to present these factors in one dedicated location, therefore providing a detailed and high-quality, customer-facing API product to your users.
We launched our dedicated Swrve dev portal in the Spring of 2022. We built the Swrve dev portal in Stoplight from a combination of our existing Help Center documentation and our OpenAPI Swagger documentation. It also includes some newly created API endpoints.
Who We Are
Swrve is an enterprise-grade marketing and customer engagement platform. We enable brands to connect with their customers using relevant messages, in real-time, and at scale. We provide messaging across channels like push, in-app messaging, web push, email, SMS, and OTT.
Our customers can create personalized, contextualized content that is shared with a specific, targeted audience using the behavioral data that Swrve provides. We are developing APIs and supporting documentation that are offered to our customers as part of our move towards a programmable customer experience (CX), which is highly personal, contextual, and relevant.
Our organization operates as a cross-functional team; we work in an open, collaborative manner. To that end, Swrve’s dev portal has been created in collaboration between our engineering, product design, and product management teams.
Much gratitude is owed to our colleagues for their assistance in creating a high-quality dev portal, which was delivered on time and with highly encouraging initial feedback.
Our Documentation Architecture
Until this year, we created and managed both our developer-focused content and end-user material in WordPress. The process of creating or updating API documentation was manually intensive and proved difficult to keep current. We generally followed a code-first approach to developing our APIs and documentation, meaning we did not write the API descriptions up front, and supporting content was often an afterthought.
As we decided to develop a new range of programmable CX APIs, our engineering team started using OpenAPI and Swagger for development and documentation. Swagger allows you to auto-generate public API reference content, “Developers can automate the specification file through annotations in the programming source code.”
Our engineering team was also able to test the APIs whilst they developed them using Swagger. However, the Swagger documentation was problematic as it was located in a separate location to our main Help Center content. This content also lacked the level of contextual information that was presented in our existing Help Center API documentation.
We wanted to develop a solution that was tailored toward the developer community. Our aim was to use our legacy API and Swagger content in a format that met the needs of our new audience. Originally, our engineering team discussed using a WordPress plugin as part of our Help Center content, but the plugin was unsupported. We examined a variety of other solutions including utilizing an open-source framework that could be used to render our Swagger content into a branded and more usable format.
After researching API design tools, we determined that a dev portal would provide the best solution for our requirements. Stoplight presented as the best option for Swrve as it included many of the features that users look for when accessing developer documentation, including API testing capabilities, request and response examples, authentication details, and concise reference documentation.
Stoplight is a tool, “which can be used to design, develop, test, and document HTTP APIs using industry standards like OpenAPI, and Markdown for written-form documentation.” By employing Stoplight for our API documentation, we have a centralized, industry-standard documentation portal for both API references and contextual information. Stoplight allows us to implement a two-column approach to our API documentation, which many industry leaders apply to their dev portal content as it provides clear grouping and easy navigation.
Stoplight also provides a means to produce design-first APIs. As shown in the figure, a design-first approach allows for the API to be designed and documented based on business input prior to the code being created.
GitHub is the content repository for all of our documentation. GitHub is synced with Stoplight and acts as the source of truth for all of our Swrve content. By hosting our content in a GitHub repository, both internal and external parties can contribute through a pull request process.
Using GitHub is also more appealing to our engineers, who regularly employ this tool as part of their development process. Our engineering teams are able to work in GitHub using the pull request functionality rather than having to work directly within Stoplight, aiding a smooth transition towards using our new dev portal.
Getting Started With Stoplight
Getting started with Stoplight is very straightforward as the tool is intuitive and user-friendly. The first port of call when getting started is the creation of a workspace. From the workspace, projects are created: “Projects help you design, store, and publish API descriptions, style guides, Markdown articles, and images.”
We created an API documentation project, which is synced with our GitHub repository. The project contains a collection of getting started, overview, tutorial, and API documents. The API documentation is created as YAML or JSON files. The other types of documentation mentioned are created as Markdown files, using Stoplightflavored Markdown.
When migrating legacy content, you can import an existing file when an API is created; alternatively, text that has been stripped of its formatting is added manually. We imported our existing Swagger content into Stoplight as YAML files, which was then categorized and utilized as required.
The following example shows a snippet from our dev portal, which depicts the tutorials and some APIs in our navigation pane, and the opening section of a tutorial.
What We’ve Found
Stoplight has allowed us to create and manage API content and Markdown files in one location. Although it’s a relatively new tool, it has a lot of sophisticated functionality, yet the user interface is quite straightforward to use. The Swrve dev portal is consistent with our brand and tone of voice; Stoplight has facilitated the transition of our content from one tool to another with relative ease.
Our engineering team has readily accepted the tool and has taken it upon themselves to provide technical support where our technical communicators have encountered complex technical issues. For example, they actively provided input on an issue we encountered with presenting multiple 400 error codes in the response example.
As we are able to perform a pull request in GitHub, based on the editorial work that is done in Stoplight, our engineers are able to use a tool and a process that they regularly use; therefore we get better input on the content that is created.
Our documentation is becoming more involved upfront in the design process. As our process becomes more aligned amongst documentation and engineering, Stoplight provides a tool that aids this collaboration. Although we haven’t fully moved towards an API design-first process model, employing Stoplight has provided a stepping stone toward this approach.
In terms of best practices when using Stoplight, I would recommend:
- Using the Stoplight documentation and Discord community. They are both useful resources for troubleshooting issues and learning about the features that Stoplight offers and can be integrated with.
- Having a process in place for managing GitHub branches and pull requests to avoid merge conflicts. I have documented our Swrve process in a Library project in Stoplight, which we use for internal reference.
- Creating a style guide document, which is easily accessible by all of the approved project editors. This is a great resource when you have various hands working on a project. Stoplight offers a linting tool, Spectral, which allows you to create your own style guide rules within the project to ensure that your style guide is adhered to. Stoplight has also recently rolled out a new style guide feature, which will allow for easier integration of style guide rules within a Stoplight project.
Although the tool has provided us with an easy-to-navigate, professional-looking interface, we have encountered some issues with Stoplight, such as:
- The use of large snippets of JSON in Markdown files causing the entire navigation pane to disappear. The use of small code snippets doesn’t present the same issue. We found a workaround by removing the JSON from the files, as it was already presented within the API documentation at endpoint level. Therefore, we reference the relevant endpoints within these documents.
- The content not appearing in the main workspace once a pull request has been done. Our engineering operations team worked with our Stoplight webhooks to ensure the lag between the content being merged and appearing in Stoplight was vastly reduced.
Looking to the Future
The current Swrve dev portal is the first version of our portal. There are a lot of options for how to build out the portal further using Stoplight. Stoplight offers an open-source tool, Elements, which is an “API Documentation toolkit, leveraging OpenAPI and Markdown to provide beautiful, interactive API reference documentation, that you can integrate with any existing content-management system or single-page application.”
As we move forward, we plan to incorporate Elements with a static site generator, such as GatsbyJS. “A static site generator is a software application that creates HTML pages from templates or components and a given content source…Static site generators, on the other hand, generate HTML pages during a build process….These generated pages are then deployed to a web server.” By utilizing a static site generator, our content won’t require “databases or any other external data sources—avoiding opportunities for security breaches and time-consuming server-side processing.”
There are various new APIs planned as part of our dev portal offerings. We are planning to move towards a design-first approach when creating our APIs. We will also continue to migrate our API and SDK documentation into Stoplight so that we have a one-stop-shop for all our developer documentation. As part of this migration, we will look at how best to restructure our content to make the best use of Stoplight’s functionality.
Conclusion
Stoplight has provided us with a professional, easy-to-maintain space for managing developer interactions with our APIs. Although Stoplight has some teething pains, which can cause issues when you have a number of hands working on the content, it successfully provides end-to-end development of APIs and their supporting documentation.
Interested in seeing more? Check out our Swrve dev portal.
Glossary
API: Application Programming Interface. A set of definitions and protocols, which define communication between applications.
OTT: Over-The-Top. TV or film content that is streamed over the internet.
HTTP: Hypertext Transfer Protocol. Application-level protocol for exchanging files online.
JSON: JavaScript Object Notation. A lightweight data-interchange format, which is easily read by humans.
YAML: YAML Ain’t Markup Language. A superset of JSON that offers a high level of nesting capability, which is useful for complex data structures.
HTML: HyperText Markup Language. The standard markup language for web pages.
SDK: Software Development Kit. A set of software development tools used by developers to integrate applications.
