ToolStation - Internal Docs
Routes

Taxonomies

The following API routes are available under the taxonomies prefix. These routes are cached with public headers and a max age of 300 seconds .

The following API routes are available under the taxonomies prefix. These routes are cached with public headers and a max age of 300 seconds .

List of API end-points prefix taxonomies

  1. GET: /taxonomies/_ping
  2. GET: /taxonomies
  3. GET: /taxonomies/top-level
  4. GET: /taxonomies/{taxonomyId}

Middleware

  • Cache Headers: All routes under this prefix have caching headers set to public with a max_age of 300 seconds.

Routes Prefix /taxonomies

1. Health Check

  • GET /taxonomies/_ping
    • Controller: PingController
    • Description: Checks if the API is alive and responsive.
    • Request:
      • Method: GET
      • URL: /taxonomies/_ping
      • Parameters: None
    • Response:
      {
data:
{
  "status": "ok"
}
}

2. GET: ../taxonomies

  • Namespace and Imports: The controller is part of the App\Http\Controllers\Api namespace
  • Service Dependencies: Utilizes TaxonomyHierarchyService retrieves the taxonomy hierarchy specifically tailored for use in menus. It fetches the full taxonomy tree, including related data, and filters it to include only those taxonomies that are designated for menu display.
  • Description: The TaxonomyController handles HTTP requests related to taxonomy data. It utilizes the TaxonomyHierarchyService to retrieve and cache taxonomy hierarchy information and returns it as JSON responses.
  • Constructor
    public function __construct(TaxonomyHierarchyService $taxonomyHierarchyService)
    • Parameters
      • TaxonomyHierarchyService $taxonomyHierarchyService: The service class for managing taxonomy hierarchies.
  • Request:
    • Method: GET
    • URL: https://base_url/ecom/v1/taxonomies
    • Parameters:
      • summary (optional) (string): If set to 'true', returns a summarized version of the taxonomy hierarchy. If not provided or set to any other value, returns the full taxonomy hierarchy.
  • Response:
    • Status: 200 OK
    • Response:
      {
  "data": {
  "menu": "integer",
  "parent_id": "integer",
  "order": string,
  "ancestors": [
      {
       "menu": "integer",
       "parent_id": "integer",
       "order": string,
      }
               ],
  "taxonomy": {
            "id": x,
            "name": "WD-40",
            "locales": {},
            "colour": "000000",
            "image": "https://cdn.toolstation.nl/images/140211-NL/250/58750.jpg",
            "slug": "wd-40",
            "description": "example",
            "notes": []
        },
   "children": []
  // other fields...
 }
}
  • Error Response:
  • Status: 404 Not Found
    • Reason: Taxonomy data could not be found. 
      {
"error": "Taxonomy data not found"
 }

Notes:

  • The response is returned in JSON format.
  • If config('taxonomy.use_taxonomy_resources_db_for_taxonomy_endpoint') is enabled, the system will attempt to fetch the taxonomy from the taxonomy resources database. If the taxonomy is not found, it will fall back to fetching via a cache.
  • Ensure that the URL and parameters are correctly specified to avoid such errors.

3. GET: ../top-level

  • Namespace and Imports: The controller is part of the App\Http\Controllers\Api namespace
  • Service Dependencies: Utilizes TaxonomyHierarchyService to fetch top-level departments from the taxonomy hierarchy. This service retrieves the departments marked for display in menus.
  • Description: The TaxonomyController topLevel method handles requests for top-level taxonomy data. It fetches and caches the top-level department hierarchy, returning it as a JSON response.
  • Constructor
    public function __construct(TaxonomyHierarchyService $taxonomyHierarchyService)
    • Parameters
      • TaxonomyHierarchyService $taxonomyHierarchyService: The service class for managing taxonomy hierarchies.
  • Request:
    • Method: GET
    • URL: https://base_url/ecom/v1/taxonomies/top-level
    • Parameters: None
  • Response:
  • Status: 200 OK
    • Response:
      {
  "data": {
  "menu": "integer",
  "parent_id": "integer",
  "order": string,
  "ancestors": [],
  "taxonomy": {
            "id": x,
            "name": "WD-40",
            "locales": {},
            "colour": "000000",
            "image": "https://cdn.toolstation.nl/images/140211-NL/250/58750.jpg",
            "slug": "wd-40",
            "description": "example",
            "notes": [
                     {
                    "id": ,
                    "name": "meta-title",
                    "value": "Deals kopen? Bekijk Deals | Toolstation"
                },
                {
                    "id": ,
                    "name": "meta-description",
                    "value": "Op zoek naar Deals? Bekijk ons grote aanbod Deals online! ✓ Gratis bezorging vanaf €20,- ✓ Professionele merken ✓ Volgende werkdag in huis"
                },
                {
                    "id": ,
                    "name": "mega-menu",
                    "value": "1"
                }
                   ]
        },
   
  // other fields...
 }
}
  • Error Response:
  • Status: 500 Internal Server Error
    • Reason: Taxonomy data could not be found. 
      // example response
{
"error": "Unable to retrieve top-level taxonomy data"
 }

Notes:

  • The response is returned in JSON format.
  • The top-level department hierarchy is fetched from the cache. If the cache entry does not exist, the hierarchy is retrieved from the taxonomy service and then cached.
  • Ensure that caching configurations and service availability are properly managed to avoid errors in data retrieval.

4. GET: ../{taxonomyId}

  • Namespace and Imports: The controller is part of the App\Http\Controllers\Api namespace
  • Service Dependencies: Utilizes TaxonomyHierarchyService to fetch top-level departments from the taxonomy hierarchy. This service retrieves the departments marked for display in menus.
  • Description: The TaxonomyController get method returns the taxonomy tree for a specified taxonomy ID. It retrieves the taxonomy data, caches it for efficient retrieval, and handles cases where the taxonomy may not be found or errors occur during the process.
  • Constructor
    public function __construct(TaxonomyHierarchyService $taxonomyHierarchyService)
    • Parameters
      • taxonomyId (path parameter) (required): The unique identifier of the taxonomy to retrieve. This must be a numeric value.
  • Request:
    • Method: GET
    • URL: https://base_url/ecom/v1/taxonomies/{taxonomyId}
    • Parameters:
      • taxonomyId (int):The ID of the taxonomy to fetch.
  • Response:
    • Status Code:
      • 200 OK if the taxonomy is successfully found and retrieved.
      • 404 Not Found if the taxonomy does not exist.
      • 500 Internal Server Error if an exception occurs during the retrieval process.
      • Content-Type: application/json
    • Response:
        // Example:- https://base_url/ecom/v1/taxonomies/x
  {
    "data": {
            "menu": "1",
            "parent_id": "0",
            "order": 19,
            "ancestors": [],
            "taxonomy": {
            "id": x,
            "name": "Verwarming & Ventilatie",
            "locales": {
                        "EN": {
                        "name": "Ventilation & Heating",
                        "description": "Ventilation & Heating"
                            }
                        },
            "colour": "000000",
            "image": "https://cdn.toolstation.nl/images/140211-NL/250/58750.jpg",
            "slug": "wd-40",
            "description": "example",
            "notes": [
                     {
                    "id": ,
                    "name": "meta-title",
                    "value": "Deals kopen? Bekijk Deals | Toolstation"
                },
                {
                    "id": ,
                    "name": "meta-description",
                    "value": "Op zoek naar Deals? Bekijk ons grote aanbod Deals!"
                },
                {
                    "id": ,
                    "name": "mega-menu",
                    "value": "1"
                }
                   ]
        },
  }
  • Error Response:
    • Status: Not Found (404 Not Found):
      • Reason: Taxonomy data could not be found.
      // example response
{
"error": "Resource Not Found"
 }
    • Status: Internal Server Error (500 Internal Server Error)
      // example response
{
"error": "An unexpected error occurred."
 }

Details:

  1. Validation: The method first checks if the taxonomyId is numeric. If not, it returns a 404 Not Found response.
  2. Caching: Uses caching to store the response of the taxonomy data for improved performance. The cache key is based on the taxonomy ID.
  3. Taxonomy Retrieval:
    • Retrieves the taxonomy using TaxonomyHierarchyService.
    • If the taxonomy is not found, logs the event and returns a 404 Not Found response.
  4. Exception Handling: Catches any exceptions that occur during the process, logs the error, and returns a response.

Logging:

  • Logs informational messages if the taxonomy is not found.
  • Logs errors if exceptions occur during the retrieval process.

Notes:

  • Caching: The method uses the Cache::remember function to store the response based on the taxonomy ID, with a cache duration specified by _tsc('products.cache.taxonomy').
  • Error Handling: Detailed error messages are logged for troubleshooting, and appropriate HTTP status codes are returned based on the outcome of the request.

Trade Credit

Countries

The following API routes are available under the countries prefix. These routes are cached with public headers and a max age of 3600 seconds .

Copyright © 2026