When open-sourcing our developer documentation framework in 2011, we created Swagger — a simple yet efficient way to describe your API.
From that JSON specification, we built interactive documentation, code generation, and server-side tooling to keep your Swagger Specification up-to-date. It’s a contract for your API — a way for developers to know what they’re going to get. Is the response an object? An array? What are the allowable query parameters? All these questions need to be answered efficiently or time is wasted either doing forensics or debugging.
Ever wanted to expose your API sandbox with OAuth 2? Here’s a short guide on enabling the Implicit or Bearer flow with swagger.
Swagger is an interface to your API, and it’s only appropriate that required authentication is described in that interface. We therefore model the OAuth2 implicit flow in the Resource Listing:
In the above, we first enumerate the scopes that this API may request permission to. The scopes are listed with descriptions, and in this sample, are all about pets.
Making Wordnik Faster
Every team and company accumulates at least a little technical debt. The trick is figuring out how to address it.
When Chiao joined Reverb, we had the opportunity and the frontend muscle to clean up some of the technical debt our products had accumulated. Wordnik.com especially hadn’t been receiving the love it deserved, so we committed to a six-week project to make the frontend codebase faster and cleaner.
The main problems we wanted to tackle with this rewrite were frontend performance and codebase complexity.
Let’s say you start a project with MongoDB. It is (and probably should be) simple and small. It starts getting some traction and expands. Your single server is now behind a load balancer and your EC2 instance sizes are getting larger and larger.
Someone reminds you to start backing up your data, and you switch to run replica sets. People are using and loving your service, and downtime isn’t an option. Your mongodump snapshots are getting huge, and it’s clear that you’re going to have data scale issues.
Browsing any of the hundreds of articles about MongoDB can teach you a ton of best practices from people who have been to war with growth. But what do you do when your system starts getting too big to change without a day of downtime?
You may have heard the news: recently Reverb released its Reverb app for iPad.
The Reverb app leverages Wordnik’s fundamental understanding of words and content, and combines it with state-of-the-art NLP and computing to build a personalized, dynamic Word Wall.
Understanding this content requires a complex pipeline of processing and literally hundreds of servers. To say APIs are important here would be a huge understatement—the Reverb app is powered by over 35 different service types and roughly 500 different API operations.
Reverb founder (and sewing enthusiast) Erin McKean has long been a fan of Spoonflower, a site that allows people to design, print and sell their own fabric, wallpaper, decals and gift wrap. When Erin found out Spoonflower was looking to use the Wordnik API to build their new tagging feature, it was like a match made in sartorial heaven.
Today we talked to Spoonflower web developer Stephanie Anton to find out more about their new tagging feature and how the site is using the Wordnik API.
Show me the code!
On my first day at Reverb, I was terrified.
I had been at my previous company for six years and was very comfortably established. I knew who to go to for help, I had my lunch crew, and everyone knew about my Hello Kitty obsession.
But it took me a while to get there. It was a month before I started talking to people, six months before I began eating lunch with others, and a year before I revealed my love for the bow-wearing cat. Now, at Reverb, I had to start all over. This was when my coworker said to me: “You aren’t who you were six years ago.”
He was right. I didn’t have to wait so long to feel at home at my new job. I could do something about it. But what?
I started brainstorming ideas. What made my previous job so memorable? What made me happy and want to go to work every day? It was the sense of home – the amazing people and my Hello Kitty decorated desk. But how could I reproduce that in my new place?
Last Friday at Reverb we had a barn-raising.
No, we didn’t raise an actual barn (although that would have been fun, too). Instead, we took a day that we had set aside for hackathon time, and decided to work on communally-voted-on features for our existing products.
Why did we do this instead of a free-play hack day? Well, although our past hack days led to some cool stuff, one or two days just wasn’t enough for each project to go from zero to fully-deployed, and Reverb devs really like to ship. Add that to everyone having one or more “pet” features that he or she would like to see implemented as quickly as possible in our current products, and the path seemed clear: why not take a day to work together on some big things that were 1) cool and 2) more shippable, but that weren’t on the immediate product plan?
At Reverb, we’re big users of Scala. To support the language we’ve been helping with libraries including Json4s. Admittedly Scala has some problems with Json4s so we’ve been working to update it.
With the last release of Json4s, we worked a lot on performance and at improving correctness of the reflection engine. This started out as checking how viable Scala 2.10’s reflection would be for our purposes. The short answer is it wasn’t all that suited for what we wanted from it. Also it doesn’t work with Scala 2.9. ;)