API: Fetching Category-Tree (”Taxon”)

This post covers fetching of categories via REST-API and fetching of whole category trees via GraphQL.

Prerequisites

In order to perform the sign up of a customer, you should have read our introduction on how our API is built and what basic concepts have been applied:

Principles of the API

TokenForge MediaService

Variables

Throughout our tutorials, we will use Variables which are also part of our Postman collections:

{{API_URL_SHOP}} : this covers the whole URL of the REST-API including the suffix for “shop”-related endpoints

GraphQL: Fetching Tree of all categories

POST https://$hostname/api/v2/shop/graphql

Request Body:

query getTaxonTranslations {
        taxa {
            id
            code
            children {
                id
                code
                translations {
                    edges {
                        node {
                            id
                            name
                            description
                            locale
                        }
                    }
                }
            }
            translations {
                edges {
                    node {
                        id
                        name
                        description
                        locale
                    }
                }
            }
        }
    }

Response:

REST-API: Fetching list of categories

Request to fetch all root categories:

Authorization	None
Method	GET
Endpoint	{{API_URL_SHOP}}/taxons
Optional Pagination	{{API_URL_SHOP}}/taxons?page=1&itemsPerPage=30
Request Body	{ "email": "{{email}}", "password": "{{password}}" }
Request Code (Success)	200
Response Body	{ "@context":"/api/v2/contexts/Taxon", "@id":"/api/v2/shop/taxons", "@type":"hydra:Collection", "hydra:member":[ { "@id":"/api/v2/shop/taxons/MUSIC", "@type":"Taxon", "id":1, "code":"MUSIC", "translations":{ "de":{ "@id":"/api/v2/shop/taxon-translations/2", "@type":"TaxonTranslation", "id":2, "name":"Musik", "slug":"musik", "description":null }, "en":{ "@id":"/api/v2/shop/taxon-translations/1", "@type":"TaxonTranslation", "id":1, "name":"Music", "slug":"music", "description":null } } } ], "hydra:totalItems":1, "hydra:view":{ "@id":"/api/v2/shop/taxons?itemsPerPage=30", "@type":"hydra:PartialCollectionView" } }
Error Response Codes	401 - Unauthorized

Example Response:

How to build a Reference to a category?

Similar to other resources like customers and products, categories (taxons) will also be referenced via its IRI.

For instance, the IRI for a concrete root category in our example above will be: /api/v2/shop/taxons/collectibles, which basically means:

instead of using some integer based IDs we will instead the whole IRI, which contains the name of the resource (/api/v2/shop/taxons) and the code of the Taxon, here: “collectible”. The code must be unique across all categories within its parent and is the actual identifier.

For example, the main category (here: “Music”) of a product would be declared as follows:

{ 
      "mainTaxon": "/api/v2/shop/taxons/music" 
}

Good to know

1. Categories can have subcategories, which could have other subcategories, which could have ...

2. Categories, similar to products, are covered by multilingualism and must include appropriate translations in all enabled languages.