Spree Commerce

Try It Now

API Improvements

Posted on November 07, 2012 by Brian Quinn

Moving the API forward

We’ve been focusing on our API a lot recently, and several different projects have helped improve it significantly. We’ve also discovered a number of areas where we’d like to make some minor and major improvements. We’d like to share some of our plans with the community in an effort to get feedback, suggestions, ideas and help.

Recent Improvements

First I’d like to cover some of the recent changes and improvements we’ve completed:

Complete Refactoring

Our SpreeWorks product includes a brand new Backbone.js based administration interface and it required a major restructing of the old REST API. Ryan Bigg (our Community Manager) rebuilt the API from the ground up to meet the needs of the SpreeWorks project, and extended it to cover a much larger part of Spree’s overall application interface.

New Documentation Site

api.sprecommerce.com was created and launched (again by Ryan) as a brand new documentation project that covers almost every detail of the current API. This site is fully open source and available for your submissions here, with thanks to GitHub for open sourcing their API documentation project.

Upcoming Improvements

A lot of work has already gone into the new API and we’ve a whole range of new improvements planned:

Search Everywhere

Ransack has proven to be an awesome addition to Spree, and it’s proved amazingly powerful when coupled with the API. We plan to include Ransack searching capabilities on RESTful index actions, and we are going to remove the now redundant “search” actions.

Easier Template Overrides

We’ve been using RABL templates with the most recent version of the API and they’ve really helped simplify the rendering process. To enable easier output customization we’re going to allow every call to an action to supply a `template` param which will render the named template supplied.

Better Versioning

While the current API does provide some means for versioning we’ve not yet started incrementing the versions as we still consider it a work in progress. We’re reviewing several options to help make versioning simpler including VersionCake.

Better Checkout Support

Currently the API uses individual actions for each checkout state, which requires a lot of customization if you are using a custom checkout state_machine. We’re going to replace these methods with a more RESTful approach where the `update` method will accept any number of calls to migrate an order through it’s state machine.


A lot of Spree’s data is very well suited to aggressive caching, so we’re going to review some interesting caching options provided by RABL.

Long Term Goals

We’ve recognized over the passing months that the API is slowing becoming the center of many Spree implementations and we’re embracing this approach.

Work is already underway to remove all json responses from Admin controllers in favour of reusing the API directly. While this adds the API as a dependency of core it also prevents double-implementation of certain features to support javascript heavy features in the admin UI.

Longer term we plan to review the options around having all interactions from Spree’s own UI controllers routed through the API, thus providing a single location for all interactions within Spree.

Having the API become the central hub of Spree will enable the creation of applications using a wider range of technologies and languages, for things like native mobile applications, client-side store implementations, etc.

Feedback Required

As you can see we’ve got a lot of really interesting developments in the pipeline and we’re keen to get your feedback and involvement. If you’ve got something constructive to add to the conversation, now is the time to be heard:

Comment below, post to Spree User or stalk us on IRC!