Posts tagged ‘api’

Exploits found within Core and API

Please upgrade your Spree stores now to their latest gem versions 1.3.2, 1.2.4, 1.1.5 or 1.0.7.

Thanks to the work of Egor Homakov, we have located and patched two serious exploits within Spree.

The first allows a user to authenticate as a random user to the API, which could
potentially lead them to authenticating as an admin user for the store. The
second allows them to issue a Denial of Service attack against the store using
an especially crafted URL.

We have patched the 1-0-stable, 1-1-stable, 1-2-stable, 1-3-stable and master
branches for Spree, as well as released new gem versions for the stable

We strongly advise all Spree stores to upgrade to their latest gem versions so
that they are not affected by these exploits.

API Improvements

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 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!

Updated REST API

The edge version of Spree has just been updated with a newly refactored implementation of the REST API. Most of these changes involve behind the scenes implementation details as well as improved test coverage. There are, however, a few non trivial changes that you should be aware of if you rely on older versions of the REST API.

New Authentication Mechanism

The most significant change to the REST API is related to authentication. The recent adoption of Devise for authentication in general has resulted in new opportunities to improve authentication for the API specifically.

Prior to Spree 0.40.x the old method of authentication was to pass an authentication token in the header. This involved using the specially designated X-SpreeAPIKey header and passing a corresponding token value. The new approach is to use standard HTTP_AUTHORIZATION which is already nicely implemented by Devise.

If you were using curl you could achieve this authentication as follows:

<p>curl -u V8WPYgRdSZN1mSQG17sK:x /<br /></p>

Note that we are using the token as the "user name" and passing "x" as a password here. There is nothing special about "x", its just a placeholder since many HTTP Basic Authentication implementations require a password to be submitted. In our case the token is sufficient so we use a placeholder for the password.

Support for .json Suffix

It is now recommended that you consider using a .json suffic in your URL when communicating via the REST API. This is technically not a new feature - it was always possible in older versions of the REST API. We’ve updated the documentation to suggest this simpler apporach (which avoids the necessity of passing Accept:application/json in the header.)

<p>curl -u V8WPYgRdSZN1mSQG17sK:x</p>

"New on Edge: RESTful API"

The REST API is designed to give developers a convenient way to access data contained within Spree. With a standard read/write interface to store data, it is now very simple to write third party applications (ex. iPhone) that can talk to Spree. It is also possible to build sophisticated middleware applications that can serve as a bridge between Spree and a warehouse or inventory system.

The API currently only supports a limited number of resources. The current list reflects the needs of paying clients who funded the development of the API. The list will be expanded soon to cover additional resources. Adding more resources is simply a matter of making the time for testing and investigating possible security implications.

Spree currently supports RESTful access to the following resources:

  • Order
  • LineItem
  • Shipment
  • InventoryUnit

Making an API Call

You will need an API key to authenticate. These keys can be generated on the user edit screen within the admin interface. Your requests should include this key in the X-SpreeAPIKey header.

<p>curl -H “Content-Type:application/json” <br />
-H “Accept:application/json” <br />
-H “X-SpreeAPIKey: YOUR_KEY”</p>

The token allows the request to assume the same level of permissions as the actual user to whom the token belongs. The admin role is fairly "powerful" by default. Consider creating a new role and assign a more limited set of permissions. This way you can create a user and corresponding token that has more narrow permissions (ex. read only access to orders.)

HTTP Methods

Your requests must use the correct HTTP method.

  • GET for listing and viewing individual resources
  • POST for creating resources
  • PUT for updating existing resources
  • DELETE for deleting resources

Currently the API supports only the JSON format. Supporting the XML format should not be difficult since Rails supports it out of the box. Volunteers who are willing to provide a patch (and tests) for XML support are encouraged to do so.


All list actions support filtering using Search Logic parameters. For example, to view all shipments that are ready to ship and that were created since the date 2010-01-01:


NOTE: Use --globoff when passing SL params through Curl to avoid syntax issues. You can also use -i to view the return header information.

Please see the REST documentation for a more detailed explanation of the API.

This project is maintained by a core team of developers and is freely available for commercial use under the terms of the New BSD License.

Spree, Spree Commerce and the Spree logo are all trademarks of Spree Commerce, Inc.