Spree Commerce

Try It Now

New on Edge: RESTful API

Posted on January 26, 2010 by Sean Schofield

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 &#8220;Content-Type:application/json&#8221;<br />
-H &#8220;Accept:application/json&#8221;<br />
-H &#8220;X-SpreeAPIKey: YOUR_KEY&#8221; http://example.com/api/orders</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.

Searching

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:


<p>/api/shipments?search[state]=ready_to_ship&amp;search[created_at_greater_than]=2010-01-01</p>

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.