Taxonomies - Storefront API

Index

To get a list of all the taxonomies, including their root nodes and the immediate children for the root node, make a request like this:

GET /api/taxonomies

Parameters

page: The page number of taxonomy to display.
per_page: The number of taxonomies to return per page

Response

Status: 200 OK

{
  "taxonomies": [
    {
      "id": 1,
      "name": "Brand",
      "root": {
        "id": 2,
        "name": "Ruby on Rails",
        "permalink": "brands/ruby-on-rails",
        "position": 1,
        "parent_id": 1,
        "taxonomy_id": 1,
        "taxons": [
          {
            "id": 3,
            "name": "T-Shirts",
            "permalink": "brands/ruby-on-rails/t-shirts",
            "position": 1,
            "parent_id": 2,
            "taxonomy_id": 1
          }
        ]
      }
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}

Search

To search for a particular taxonomy, make a request like this:

GET /api/taxonomies?q[name_cont]=brand

The searching API is provided through the Ransack gem which Spree depends on. The name_cont here is called a predicate, and you can learn more about them by reading about Predicates on the Ransack wiki.

The search results are paginated.

Response

Status: 200 OK

{
  "taxonomies": [
    {
      "id": 1,
      "name": "Brand",
      "root": {
        "id": 2,
        "name": "Ruby on Rails",
        "permalink": "brands/ruby-on-rails",
        "position": 1,
        "parent_id": 1,
        "taxonomy_id": 1,
        "taxons": [
          {
            "id": 3,
            "name": "T-Shirts",
            "permalink": "brands/ruby-on-rails/t-shirts",
            "position": 1,
            "parent_id": 2,
            "taxonomy_id": 1
          }
        ]
      }
    }
  ],
  "count": 5,
  "pages": 2,
  "current_page": 1
}

Sorting results

Results can be returned in a specific order by specifying which field to sort by when making a request.

GET /api/taxonomies?q[s]=name%20asc

It is also possible to sort results using an associated object’s field.

GET /api/taxonomies?q[s]=root_name%20desc

Show

To get information for a single taxonomy, including its root node and the immediate children of the root node, make a request like this:

GET /api/taxonomies/1

Response

Status: 200 OK

{
  "id": 1,
  "name": "Brand",
  "root": {
    "id": 2,
    "name": "Ruby on Rails",
    "permalink": "brands/ruby-on-rails",
    "position": 1,
    "parent_id": 1,
    "taxonomy_id": 1,
    "taxons": [
      {
        "id": 3,
        "name": "T-Shirts",
        "permalink": "brands/ruby-on-rails/t-shirts",
        "position": 1,
        "parent_id": 2,
        "taxonomy_id": 1
      }
    ]
  }
}

Create

This action is only accessible by an admin user.

To create a taxonomy, make a request like this:

POST /api/taxonomies

For instance, if you want to create a taxonomy with the name "Brands", make this request:

POST /api/taxonomies?taxonomy[name]=Brand

If you're creating a taxonomy without a root taxon, a root taxon will automatically be created for you with the same name as the taxon.

Response

Status: 201 Created

{
  "id": 1,
  "name": "Brand",
  "root": {
    "id": 2,
    "name": "Ruby on Rails",
    "permalink": "brands/ruby-on-rails",
    "position": 1,
    "parent_id": 1,
    "taxonomy_id": 1,
    "taxons": [

    ]
  }
}

Update

This action is only accessible by an admin user.

To update a taxonomy, make a request like this:

PUT /api/taxonomies/1

For instance, to update a taxonomy's name, make this request:

PUT /api/taxonomies/1?taxonomy[name]=Brand

Response

Status: 200 OK

{
  "id": 1,
  "name": "Brand",
  "root": {
    "id": 2,
    "name": "Ruby on Rails",
    "permalink": "brands/ruby-on-rails",
    "position": 1,
    "parent_id": 1,
    "taxonomy_id": 1,
    "taxons": [
      {
        "id": 3,
        "name": "T-Shirts",
        "permalink": "brands/ruby-on-rails/t-shirts",
        "position": 1,
        "parent_id": 2,
        "taxonomy_id": 1
      }
    ]
  }
}

Delete

This action is only accessible by an admin user.

To delete a taxonomy, make a request like this:

DELETE /api/taxonomies/1

Response

Status: 204 No Content

List taxons

To get a list for all taxons underneath the root taxon for a taxonomy (and their immediate children) for a taxonomy, make this request:

GET /api/taxonomies/1/taxons

Response

Status: 200 OK

[
  {
    "id": 2,
    "name": "Ruby on Rails",
    "permalink": "brands/ruby-on-rails",
    "position": 1,
    "parent_id": 1,
    "taxonomy_id": 1,
    "taxons": [
      {
        "id": 3,
        "name": "T-Shirts",
        "permalink": "brands/ruby-on-rails/t-shirts",
        "position": 1,
        "parent_id": 2,
        "taxonomy_id": 1
      }
    ]
  }
]

A single taxon

To see information about a taxon and its immediate children, make a request like this:

GET /api/taxonomies/1/taxons/1

Response

Status: 200 OK

{
  "id": 2,
  "name": "Ruby on Rails",
  "permalink": "brands/ruby-on-rails",
  "position": 1,
  "parent_id": 1,
  "taxonomy_id": 1,
  "taxons": [
    {
      "id": 3,
      "name": "T-Shirts",
      "permalink": "brands/ruby-on-rails/t-shirts",
      "position": 1,
      "parent_id": 2,
      "taxonomy_id": 1
    }
  ]
}

Taxon Create

This action is only accessible by an admin user.

To create a taxon, make a request like this:

POST /api/taxonomies/1/taxons

To create a new taxon with the name “Brands”, make this request:

POST /api/taxonomies/1/taxons?taxon[name]=Brands

Response

Status: 201 Created

{
  "id": 2,
  "name": "Ruby on Rails",
  "permalink": "brands/ruby-on-rails",
  "position": 1,
  "parent_id": 1,
  "taxonomy_id": 1,
  "taxons": [

  ]
}

Taxon Update

This action is only accessible by an admin user.

To update a taxon, make a request like this:

PUT /api/taxonomies/1/taxons/1

For example, to update the taxon’s name to “Brand”, make this request:

PUT /api/taxonomies/1/taxons/1?taxon[name]=Brand

Response

Status: 200 OK

{
  "id": 2,
  "name": "Ruby on Rails",
  "permalink": "brands/ruby-on-rails",
  "position": 1,
  "parent_id": 1,
  "taxonomy_id": 1,
  "taxons": [
    {
      "id": 3,
      "name": "T-Shirts",
      "permalink": "brands/ruby-on-rails/t-shirts",
      "position": 1,
      "parent_id": 2,
      "taxonomy_id": 1
    }
  ]
}

Taxon Delete

This action is only accessible by an admin user.

To delete a taxon, make a request like this:

DELETE /api/taxonomies/1/taxons/1

This will cause all child taxons to be deleted as well.

Response

Status: 204 No Content