Overview

Solidus's REST API (the solidus_api gem ) is designed to let you access data contained within your store.

The API uses a standard read/write interface that returns JSON. This means that you can easily create third-party applications that can consume your Solidus store data. The API is implemented using controllers and Jbuilder views.

It is also possible to build more sophisticated middleware applications that bridge between your store and a warehouse or inventory system.

Make an API call

By default, you can make API calls if you are an authenticated user with the role of admin.

Requests

To make a request to the API, pass a X-Spree-Token header and a Spree API key along with the request:

Bash
    
      curl --header "X-Spree-Token: <key>" http://yourstore.com/api/products/1

    
  

Alternatively, you can pass through the token as a URL parameter if you are unable to pass it through a header:

Bash
    
      curl http://example.com/api/products/1?token=<key>

    
  

The token parameter allows the request to assume the same level of permissions as the actual user to whom the token belongs.

Authentication

Any user with a Spree::Role of admin has an API key generated for them when their account is created.You can get the key value from the user table's spree_api_key column.

For example, if you use the Spree::User model provided by the solidus_auth_devise gem , you can access the user's API key in your Rails console with a command like this:

Ruby
    
      Spree::User.find(1).spree_api_key

    
  

Store administrators can view or regenerate API keys from the solidus_backend interface from the Users page by editing a user with the admin role.

Endpoint rules

The Solidus API endpoints comply with the following rules:

  • Successful GET requests always return a status of 200.
  • Successful CREATE and UPDATE requests result a status of 201 and 200.
  • Successful DELETE requests return a status of 204 and no content.
  • Unauthorized requests return a status of 401 and no content.
  • When a resource cannot be found, the API returns a status of 404.
  • Failed CREATE and UPDATE requests return a status of 422 with a hash containing an error key and an errors key. The errors value contains all of the ActiveRecord validation errors encountered when saving the record.
  • Requests that list collections (like an /api/products request) are paginated and display 25 records per page by default.

Custom responses

You can customize the responses from the API in two ways:

  1. Override a view from the solidus_api gem.
  2. Provide a new view with your custom template in your application.

For example, if you wanted to override the default products/show.json.jbuilder template, you could place a file with the same path and file name in your application. In this case, your custom template should be created at the path app/views/spree/api/products/show.json.jbuilder.

Feedback

Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.