In 2015 we made a significant shift in focus to offering an API for businesses to white label the payments experience within their application. A large change came to the underlying product offering, in addition to the API that powered our primary product. As an engineering team we took time to reflect on version one of our API and made the decision to build an entirely new one from scratch.
Early on we knew we wanted to:
- Design a new API that was more pragmatic for business to business transactions
- Do it quickly
That’s where Swagger came into view and pushed us to a design-first mentality that would offer us great benefits in collaboration. The engineering team working on the API could align on a single source of truth while building the API. Our Developer Relations team used the Swagger Codegen project for releasing new SDKs and the Sales team directed potential customers to the spec to collect feedback prior to the backend APIs being completely built out.
Near the end of 2016 we drifted away from Swagger and are now making our way back to OpenAPI and the tooling that goes along with it. Before jumping into how we utilize the API spec and its benefits, we’ll take a step back and give a brief background of OpenAPI for those less familiar.
What is OpenAPI?
OpenAPI (fka Swagger), and more specifically the OpenAPI specification (OAS), is a machine-readable and human friendly file—or files—that are used to describe REST APIs. The OpenAPI spec document is a JSON or YML file that includes information relevant to building and consuming REST APIs.
- Data models
- Request and response parameters
The specification itself was donated from SmartBear Software to a collective group of industry experts that would create the OpenAPI Initiative in 2017. The OpenAPI initiative released version 3.0.0 of the spec which included a lot of updates and capabilities to better meet the needs of the Dwolla API.
What ultimately attracted me back to the specification was:
- Using links to express relationships between operations
- Better support for multi-part document handling
- Improved parameter descriptions, including the ability to use a schema, and more
The maturity of the specification, and the adoption industry-wide, showed that OpenAPI is a key cog in the API development lifecycle for any REST API provider.
Collaboration & Documentation
The Developer Relations team owns writing the API documentation that exists at https://docs.dwolla.com, which is a project that gets manually updated anytime a change is made to the API. Our team currently works alongside multiple internal engineering teams to help design, test and document the API. Over time, we’ve worked with many different engineers to get them acclimated to making changes. When the number of engineers working on the API was low, it was relatively easy to keep everyone on the same page and push out changes with confidence and efficiency. As the number of engineers and the size of the API grew, collaboration became more difficult.
Repeat questions arose, such as: do we have an existing Validation Error that solves for x? Do we have a property for x that can be reused on a new resource that’s being added? These questions were typically directed towards the few people with the domain knowledge to point you in the right direction.
It became apparent, we need to go back to the basics and spec it out.
Having a spec for our API aligns everyone with the source of truth when questions come up. This will offer other benefits for the developer relations team by being able to dynamically generate documentation based on the spec.
Maintaining API documentation by hand is less than ideal and subject to errors. As we look to replace our existing API reference docs, we’ll explore projects like redoc which generates interactive and responsive documentation from the spec itself. Having a single spec which we read from gives us the ability to push changes out quicker and with more confidence.
Migrating and Publishing Our Spec
Towards the end of 2019 I took a look at our existing Swagger 2.0 spec that we had published internally and underwent the process of migrating this to OpenAPI 3.0.2. Part of the process involved just plain writing it all down, but there were some tools used along the way which helped in getting it migrated and in a more manageable state to publish. Luckily, there were already others in the industry that had written on this topic and linked to tools like oas-kit which is an OpenAPI converter.
After converting a large JSON file to YML, I plugged it into VSCode and used the vscode-openapi extension to continue updating and cleaning it up. One of the biggest challenges in migrating our existing spec to OpenAPI 3.0.2 was going back and retroactively adding API errors, which weren’t clearly defined in our previous Swagger specification. As of this post, I have added tasks to continue breaking out the specification into separate, more consumable, files and filling in any gaps that may exist to make the spec as complete as possible. Adding niceties, such as examples and complete descriptions, will make it easier to use when leveraging the tooling that goes along with OpenAPI.
The benefits of publishing our spec extend beyond design and documentation, but also into the tooling that has been developed to support the OpenAPI specification. As OpenAPI continues to gain traction in the industry, the tooling is expanding to support all stages of the API lifecycle.
A collection of OpenAPI tools can be found at: https://openapi.tools/, but here are a few I’m interested in exploring more:
For developers looking to explore Dwolla’s API, import the spec into Postman or Swagger editor and see what the API has to offer. Are you interested in exploring generating an SDK for your language of choice? Check out OpenAPI-generator. Interested in setting up a mock server to ensure your integration is inline with Dwolla API changes? Check out Prism.
Explore the Spec
Our specification is now published on GitHub and we’ll continue to make adjustments as updates are made to the underlying API. We’re also excited to see where the OpenAPI initiative takes the specification and we’ll continue to explore how we can expand our use of OpenAPI within our ecosystem!