Using Apiary to Demo and Prototype
--
The Trunk Club Engineering team has been using Apiary for API design and documentation, as described by our engineer Jack Blandin. Not only does Apiary help you document and unblock client development, it also helps you focus on what matters — the design of the API. Both the client and backend developers get to define the constraints of the system without having to interact with the server.
But what if you can do more than that ? We can use Apiary’s concept of being a living document to help create demonstration apps and to prototype ideas.
The Trunk Club App
When a member signs up with Trunk Club, a personal stylist is assigned to the member. The stylist collaborates with the member to understand his or her needs, and uses that shared knowledge to build a “trunk” together. The trunk contains a set of clothes the stylist picked out for the member, and it gets sent to the member’s house with the stylist’s personal notes and outfit suggestions.
Our Trunk Club app (Android / iOS) makes it easy for our members to enjoy this personal Trunk Club experience. Through the app, members can message their stylist, build a trunk together, give feedback, and get style advices and outfit suggestions.
Traditionally, it’s been difficult for our stylists and the tech team to experience what it’s like to use the member-facing mobile app. Even though our stylists interact with our members all the time, it’s been hard for them to understand what the latest member-facing mobile app experience is like. Likewise, although our tech team builds a lot of great features, it’s been hard to experience it from the member’s perspective and see what we’ve built.
However, it’s not trivial to showcase this member mobile app experience, since there are a lot of activities going on. When a stylist sends out a trunk to the member, our system has to keep track of our inventory, communicate with external vendors to create shipping labels, and make sure that the member’s billing details are up to date and handled securely. Not only that, we’ve structured our architecture into microservices. Each of the tasks I just described happens in a different application, oftentimes on a different server.
It would have been impractical to create an integration environment that’s a clone of our production environment, and it wouldn’t have addressed external vendor systems like shipping and payment. It is important to protect sensitive user data, so member’s personal and financial data shouldn’t be copied over to such environments. At the same time, we need to use rich information that is as close to what would happen in the real world as possible.
We work on a lot of cool features, and it would be awesome for our own Trunk Club team to experience what we are building. It would also be helpful for stylists to see first hand what the member app experience is like. This is where Apiary comes in.
Apiary
In Apiary, you can write an API spec to define the request and response for your server endpoints. It also has a mock server mode where it will return the defined response. You can then point your client to the URL generated by Apiary in the document and get the expected responses (more on it here).
We wanted to address this and showcase our member app to the stylists and the tech team. To do this, we took a creative approach in how we can use Apiary. We created a new Apiary document dedicated for demoing. We looked at the API that serves our member facing clients, and used Apiary to stub out complementary behaviors that we want to showcase.
We took the following steps to create a demo version of our member app:
- We used Splunk to search for exemplary payloads to use as a base. This ensured that we had good data that looked real.
- We didn’t want to mock out everything on our app, so we used dependency injection to point some API calls to Apiary, while pointing the rest of our API calls to our staging environment. Our Android app uses Dagger 2 for dependency injection, so this was fairly easy to do in the Android app using Gradle build flavors.
The Result
We now have two demo stations in Trunk Club, running our latest Android app with custom data that showcase our member experience. One station is placed where the stylists work, and the other one is stationed near the design team and the tech team.
The demo app also shows the different stages of the trunks that the stylist creates for the member, from the moment it’s created by the stylist, to the point where the member can schedule a pickup. It’s fully interactive and guaranteed to return the expected demo payload no matter what you do. Even if you sign out and sign in with random data, the app will always sign in as the demo user. It’s also easy to show the latest app experience since it barely requires any app changes.
As our experience with the demo app shows, it’s easy to set up mock endpoints on Apiary to generate the payload you want. Because of this, we also used Apiary for one of our Hack Day projects. It worked well since using Apiary allowed for parallelization of work, on-the-fly customization of the payload, and hot swapping of mock and real endpoints as the backend got built. Best of all, at the end of the project, we already had a fully thought out API spec. Apiary is well suited for quick prototyping and proof of concepts, so I encourage you to experiment with it outside of normal feature work!
Thank you for reading! Feel free to say hi or share your thoughts on Twitter @hiBrianLee or in the responses below!
Some of my other posts:
