Gusto Embedded is focused on building the most developer-friendly payroll APIs, and we’re always looking for ways to improve the experience. This blog post is about a major API infrastructure project we’ve been working on to reduce time to launch, ensure partners build a more bug-free embedded payroll experience, and get new API features into partner engineers’ hands faster.
To accomplish this, we partnered with Speakeasy to automatically generate API client libraries from our OpenAPI spec in some of the top languages our partners use to build embedded payroll. By replacing a critical step that every partner takes in the development process, we aimed to remove weeks of upfront build time, and to reduce the ongoing maintenance cost of custom client libraries. We’ve automated an extremely manual and error-prone process for both our partner developers and our internal consumers of the API, such as the React SDK. And we’ve matured as a team in how we maintain the accuracy of our OpenAPI specs and documentation, growing partner trust as they build with our technology.
Build vs Buy: How we decided
Before we even started to generate any code, we explored all possible options, building proofs of concept in a variety of tools and doing in-depth research on the features offered by several different vendors. First, we examined a few popular open source tools, such as OpenAPI Generator, that would enable the most flexibility in generating code. Then we compared those with vendors that provide code generation out of the box along with the broad language expertise required to make the project successful.
To bring this powerful automation to partners swiftly and effectively, we made the strategic decision to integrate with a leading vendor in this space rather than undertaking a full in-house build. This allows our team to laser-focus on ensuring the automation works seamlessly within our system and delivers maximum value to our partners quickly. Building and maintaining a robust code-generation pipeline across multiple languages would have diverted significant resources, and our priority was to make this new automation a core strength of our platform, not a side project. A partnership allows us to leverage expertise to deliver a polished and reliable solution immediately.
Enter Speakeasy, which we chose for several reasons: the great UX of their command line and CI tools, their willingness to partner with us to drive the development of their Ruby code generator, and their strong commitment to OpenAPI standards over proprietary configurations.
Scaling the Impact of our OpenAPI specs with Speakeasy
Working with a company like Speakeasy has allowed us to quickly (in a matter of weeks!) generate and distribute libraries in languages that our partners rely on, like C# and Java, but that we have little experience with internally. With Speakeasy, we not only get client and type generation, but also documentation, code snippets, and runtime validation of inputs and outputs to the API—features that could’ve taken us years to build internally, even in just one or two languages.
To ensure partners always have access to the latest features of our API through these client libraries, we implemented a new set of build pipelines to check for changes to our OpenAPI spec, and generate changes to each client library on a nightly basis. After an engineer checks those code changes using the typical Github pull request review process, the changes are automatically released and distributed via the common package management tool for each language.
The Results: New API Clients, a Better Overall API, and a Better React SDK
One of the most exciting and unforeseen effects we’ve found in using these generated API clients is that our OpenAPI specification is in much better shape now. Working with Gusto Embedded’s React SDK team, we were able to dogfood the generated API clients, and uncovered some of the more nuanced errors in our OpenAPI spec. This is critical feedback that we’ve previously only been able to get when external partners report bugs to us. Since the OpenAPI spec is now the source of truth for both our documentation site and our generated client libraries, these improvements to the OpenAPI spec driven by API client usage directly lead to improvements in our documentation, making both much more accurate.
We’re still in beta, so the partners using our API clients aren’t live yet, but we’re already seeing improvements in their development speed. We’re confident partners using our API clients will be able to launch their payroll products faster, and we’ll continue to work closely with our partner developers to drive adoption of these libraries and gather feedback to improve the usability of our generated code.
So far we’ve gathered largely positive feedback from Gusto Embedded’s React SDK team. After migrating their system to use our new auto-generated Typescript library, they now barely have to think about the API layer when building new features. They used to have to spend time iterating on our OpenAPI spec before managing their own partially generated and partially hand-written client code, but that entire stream of work has been abstracted away, speeding up the time to deliver each new component, allowing them to dedicate more energy to building reliable React components that meet their users’ needs.
What’s next
If your team is maintaining your own bespoke API client, or beginning to evaluate partners for implementing embedded payroll, consider using one of the API clients we offer! We are currently looking for partners who are willing to work closely with us and provide feedback on our auto-generated client libraries while also speeding up their build times. As this project is in beta, we are actively making improvements and any feedback from your team will be instrumental in this project’s development.
