Taxonomies - Storefront API | Spree - Ruby on Rails e-commerce platform

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/v1/taxonomies

Parameters

page: The page number of taxonomy to display.
per_page: The number of taxonomies to return per page
set: Displays the complete expanded taxonomy tree if set to nested.

Response

Status: 200 OK

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

            ]
          }
        ]
      }
    }
  ],
  "count": 25,
  "current_page": 1,
  "pages": 5
}

Search

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

GET /api/v1/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",
        "pretty_name": "Ruby on Rails",
        "permalink": "brands/ruby-on-rails",
        "parent_id": 1,
        "taxonomy_id": 1,
        "meta_title": "Ruby on Rails",
        "meta_description": "Ruby on Rails",
        "taxons": [
          {
            "id": 3,
            "name": "T-Shirts",
            "pretty_name": "T-Shirts",
            "permalink": "brands/t-shirts",
            "parent_id": 1,
            "taxonomy_id": 1,
            "meta_title": "T-Shirts",
            "meta_description": "T-Shirts",
            "taxons": [

            ]
          }
        ]
      }
    }
  ],
  "count": 5,
  "current_page": 1,
  "pages": 2
}

Sorting results

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

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

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

GET /api/v1/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/v1/taxonomies/1

Response

Status: 200 OK

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

        ]
      }
    ]
  }
}

Create

This action is only accessible by an admin user.

To create a taxonomy, make a request like this:

POST /api/v1/taxonomies

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

POST /api/v1/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",
    "pretty_name": "Ruby on Rails",
    "permalink": "brands/ruby-on-rails",
    "parent_id": 1,
    "taxonomy_id": 1,
    "meta_title": "Ruby on Rails",
    "meta_description": "Ruby on Rails",
    "taxons": [

    ]
  }
}

Update

This action is only accessible by an admin user.

To update a taxonomy, make a request like this:

PUT /api/v1/taxonomies/1

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

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

Response

Status: 200 OK

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

        ]
      }
    ]
  }
}

Delete

This action is only accessible by an admin user.

To delete a taxonomy, make a request like this:

DELETE /api/v1/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 children) for a taxonomy, make this request:

GET /api/v1/taxonomies/1/taxons

Parameters

without_children: Displays only immediate children of taxons if set to true.

Response

Status: 200 OK

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

          ]
        }
      ]
    }
  ],
  "count": 7,
  "total_count": 7,
  "current_page": 1,
  "per_page": 25,
  "pages": 1
}

A single taxon

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

GET /api/v1/taxonomies/1/taxons/1

Response

Status: 200 OK

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

      ]
    }
  ]
}

Taxon Create

This action is only accessible by an admin user.

To create a taxon, make a request like this:

POST /api/v1/taxonomies/1/taxons

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

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

Response

Status: 201 Created

{
  "id": 2,
  "name": "Brands",
  "pretty_name": "Brands",
  "permalink": "brands/brands",
  "parent_id": 1,
  "taxonomy_id": 1,
  "meta_title": "Brands",
  "meta_description": "Brands",
  "taxons": [

  ]
}

Taxon Update

This action is only accessible by an admin user.

To update a taxon, make a request like this:

PUT /api/v1/taxonomies/1/taxons/1

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

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

Response

Status: 200 OK

{
  "id": 2,
  "name": "Brands",
  "pretty_name": "Brands",
  "permalink": "brands/brands",
  "parent_id": 1,
  "taxonomy_id": 1,
  "meta_title": "Brands",
  "meta_description": "Brands",
  "taxons": [
    {
      "id": 3,
      "name": "T-Shirts",
      "pretty_name": "T-Shirts",
      "permalink": "brands/t-shirts",
      "parent_id": 1,
      "taxonomy_id": 1,
      "meta_title": "T-Shirts",
      "meta_description": "T-Shirts",
      "taxons": [

      ]
    }
  ]
}

Taxon Delete

This action is only accessible by an admin user.

To delete a taxon, make a request like this:

DELETE /api/v1/taxonomies/1/taxons/1

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

Response

Status: 204 No Content