On larger software projects, one of the biggest challenges to a successful and timely delivery is aligning the efforts of multiple teams. Understanding the web of interdependencies and planning the development schedule of related subsystems is a full-time job on many projects. Even with careful milestone planning and employment of agile techniques complex projects inevitably run into situations where the efforts of one team are blocked by a late deliverable from another team. As enlightened software developers, we understand that no amount of planning ahead of time can force a creative endeavor like software engineering to fit neatly on a calendar. But we also recognize that no amount of flexibility and agile pivoting can completely mitigate the fact that sometimes teams will be blocked waiting on other deliverables. So how can we minimize the risk to the overall product timeline? In mobile development, especially large scale Enterprise integration projects, we most frequently run into situations where a backend API is not complete enough to proceed with client application development. In those situations, what we really wanted was a way to allow development of each to proceed unimpeded by the other. Just as our software architecture aimed to be a set of loosely coupled components, our development process needed to minimize interdependencies, allowing teams to work on different parts in parallel while communicating through common interfaces.
Decoupling API Development
In order to decouple API and client development, effectively allowing concurrent development on each, we found we needed two key things:
A common description format for an API to serve as the primary reference for any team interacting with the API. This description should be the canonical point of validation for the API itself as well as any systems that interact with it. It should provide human readable documentation to aid development and be a machine-readable specification that tooling can build on.
A way to simulate an API to facilitate client development and functional testing. In other words, we wanted a way for client mobile app developers to be able to hit an API that did not yet exist.
To reach our first goal, we decided not to reinvent the wheel by creating our own API specification format. Instead, we opted to use Swagger. It’s an open API specification maintained by the folks at Reverb. Swagger, now on the 2.0 version, is appealing for several reasons:
- It’s Open - Swagger is maintained by Reverb’s talented team, but is entirely open source and community supported.
- Great Tools - Over the years the Swagger community has created a wide variety of tools and integrations that leverage the power of a machine-readable API specification. Many developers are familiar with the fantastic Swagger UI project, but tools are also available for client and server code generation and static documentation.
- Wide Adoption - Most API platforms have the ability to automatically generate Swagger specs, and there are thousands of production Swagger deployments. Ideally, our solution would play nicely with all of them.
As far as the tool itself, we knew we wanted something that focused on the needs of API developers first and foremost. We worked with our design team to create a beautiful, intuitive user experience. Creation and modification of models to describe Json output is also intuitive. Describing HTTP requests and responses is flexible and easy. Static documentation or a Swagger sandbox can be generated at any time. You don’t need to be a back-end engineer or learn a new data description format in order to use Monkeypod. And then there’s the virtual API, aimed squarely at developer productivity. A virtual version of the API, serving mock data, is immediately live once the project is created. Changes made to the API design are immediately reflected in the virtual API. Beyond serving simple random strings and numbers, the virtual API requests can be tailored using a powerful system of cascading configuration descriptors. Data values to look like human names, numbers within a specified range, or values pulled from a specified enumeration, for example. Monkeypod can simulate latency, large payloads, and other edge cases developers want to test their client apps against. With the virtual API, we’ve really run with the idea of “eating our own dog food." In a recent refactor of Monkeypod itself, we needed to avoid blocking the front end team while we made changes to the Monkeypod API and models. Solution? Build the next version of the Monkeypod API in Monkeypod itself. We were able to quickly see a working version of the tool with the front-end changes, and to adjust the API accordingly, developing each in parallel. The Future For us, this beta launch is only the beginning. We want Monkeypod to be the most useful API design, development and virtualization tool we can make it, and we have a lot of exciting ideas going forward. We’ll continue to offer more flexible configuration of virtual API responses, including management of test data suites. Validation and verification, as well as tools to facilitate great standards-based APIs are on the roadmap. And we have some exciting plans around fast, flexible API deployment. We’d love to hear your thoughts and ideas about Monkeypod. Sign up for an invitation to the private Beta at http://monkeypod.ioFollow us on twitter at http://twitter.com/monkeypodio