This is a guest article written by Brian Hyder, Engineering Manager @ Dude Solutions.
Dude Solutions is a leading software-as-a-service (SaaS) provider of operations management solutions recognized for world class delivery, support and a long-standing commitment to innovation.
Here at Dude Solutions, we have two front facing REST APIs that drive our platform: Unified and Security. Unified provides the collections for driving normal business functions for our verticals while our security API handles account and user management. These two APIs are supported by a set of micro-services that specialize in different areas: Notification, Event, Report, and File. The short name of each gives a good indication of the primary business function that each one performs.
The Need for SDKs
The first time we thought about SDK development was early on in the development of our new platform. We needed to communicate from our Security API to our notification micro-service in order to send notifications on creation of accounts and users. By building an SDK we now had sharable software that we could use across the entire platform. It reduced the amount of code in each API stack and understood our security protocols.
We decided to write our first SDK by hand. We learned that it takes almost as long to do the API implementation as it did the SDK development. In fact, it took one week to develop the SDK for a single language. We have 3 languages across our platform:
- C# for our API layer
- Ruby for our API Automation
- Angular for our UI
That’s a lot of development time compared to the effort to implement the API itself. We weren’t getting the return on investment that we expected despite the reduction in code.
When we began to iterate over the design for the next micro-service, we started to look into alternate forms of documenting our APIs. We came across API Blueprint format, an open source documentation standard for APIs. It was easy to read and the syntax was familiar to our developers since it looked like Markdown format. This discovery lead us to APIMatic, and we quickly started conversations with their team. They got us up and running with a proof of concept within a couple of weeks. The POC demonstrated that we could drastically reduce development time by generating the SDK off of our blueprint documentation. Since the blueprint was generated during the design phase, the cost of SDK was absorbed by the time and money spent on design.
The development time for SDKs for each language went from 1 week to 18 seconds thanks to APIMatic.
In 3 months, across the 7 SDKs that we generate, we’ve been able to save $20,000 in development costs. Additionally, the cost of maintenance is also eliminated because the effort to update the SDK each time the API changes is absorbed as part of the feature’s design cost.
Collaboration using Contract-First Approach
The one issue we ran into developing the first SDK by hand was the development teams working in silos. The initial design was based off of the implementation for the API. This meant if development on the SDK started in parallel there were differences in the API contract when compared to the expectations of the SDK. Teams had to slow down and execute in series: API implementation, SDK development, API automation testing, UI development, and UI automation tests.
Incorporating the API blueprint documentation into our design process allowed for developers to iterate quickly over the design of the API while having a definitive source of information for how the API would behave. The days of outdated wiki pages were over. Developers could now work collaboratively on design and work in parallel on: API implementation, API automation, UI development, and UI automation tests. We had finally achieved a contract first approach to development.
The contract first approach worked because we integrated the design process into our normal development process. The blueprint document is versioned in a Git repository. At Dude Solutions, we use normal Git flow for our branching model. This means each change to our API starts by branching off the development branch for the documentation repository. Then, developers can put changes to the API documentation into a pull request. This is beneficial because all of our teams have notice of the changes that are happening. Once a change to the documentation is made and pushed back to the repository our continuous integration system takes over from there.
Automate All the Things
We leverage a feature called “Feature Branching” in Team City, our build system. It allows for builds to kick-off for each branch when a change is made to our blueprint documentation. This gives almost instant feedback to developers about the change that they made. The continuous integration allows developers to generate a new version of the SDK seconds after a change to documentation and begin to integrate and test it in local environments all within a couple of minutes.
Thank you APIMatic
APIMatic and the APIMatic Team have been amazingly helpful from the very beginning. The response times, to support and change requests have been met with blazing speed. The APIMatic platform not only saves us time and money, it makes our lives much easier. Our engineers can focus on doing something incredible and less time worrying about integrations. We owe a big thanks to the APIMatic team for their help and support over the past couple of months.