We recently added an API to The Winnower to support our new Wordpress Plugin. It was a great experience in both product and software design. Wordpress support is the first of a few great features we're adding to The Winnower to aid our users in publishing.

It was suprising to me, but these days a lot of academic publishing, if not in journals, is done on blogs. The Winnower provided publishing services to papers which were uploaded via Word or Latex, but people would have to copy their blog published papers from whatever they currently use into Word if they wanted publish them. That wasn't great.

Wordpress.org is one of the largest blogging software platforms. It's crazy customizable and very easy to use. It was a very good first candidate to support. We figured a Wordpress plugin would allow people to keep publishing as they do now, and allow them to get DOI's and go through the open review processes through The Winnower.

The plugin needed to integrate with the site via some sort of API, and we wanted to adopt the JSON Api spec wich describes a restful JSON interface. Internally, the Winnower's APIs were a bit of a mess. The site had evolved a lot since the initial structure was created and the technical debt that had accrued caused the APIs to loose some of their elegance. Because of that, they didn't map cleanly to JSON API, or any other restful API.

We started by "green fielding" the API design to match the needs of the plugin and it's users. Then we built the API alongside the existing interfaces. We built a bridge between the new and the old by creating some service objects that wrangled the internals into a reasonable shape and interface. Finally, we built out the controllers to handle the particulars of the JSON API requests.

This taught us a lot about what we really needed to publish a paper, and how we could restructure the internals across the site. Thankfully, we already had great integration test coverage for our publishing papers. We're now able to start moving towards a much better designed app without the risk of breaking everything.

The coolest part of this sprint was that we got a lot of insight into our existing user experience (UX). Much of it existed to accommodate the original design as opposed to the features the users needed. We're going to have a much easier time improving the experience after the internal restructuring and we're going to find ourselves with a much better product in the end.

-Francis

PS If you're interested in programming for The Winnower's API please let us know! In the meantime we'll keep building new uses for it. =)