Skip to main content
Version: 🚧 Canary

🛣️ Location Routes

Location routes provide pre-configured HTTP endpoints for location management operations in NodeBlocks applications. These routes combine blocks, validators, and middleware to create complete API endpoints with proper authentication, authorization, and error handling.

🎯 Overview​

Location routes are designed to:

  • Provide complete API endpoints for location management operations
  • Combine blocks with validators for secure operations
  • Include authentication and authorization checks
  • Support functional composition patterns
  • Handle logging and error management automatically
  • Support hierarchical relationships with parent-child and ancestor tracking

📋 Route Structure​

Each location route follows a consistent pattern:

  • HTTP Method: Defines the operation type (GET, POST, PATCH, DELETE)
  • Path: Specifies the endpoint URL with parameters
  • Handler: Composed function chain for business logic
  • Validators: Authentication and authorization checks

🔧 Available Location Routes​

createLocationRoute​

Creates a new location via POST /locations with parent hierarchy support and ancestor building.

Purpose: Handles location creation requests with automatic hierarchical relationship management, including parent location validation and ancestor chain construction.

Route Details:

  • Method: POST
  • Path: /locations
  • Authentication: Required (Bearer token)

Blocks: buildAncestorsFromParent, buildLocationToCreate, getLocationById, createLocation

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.createLocationRoute);

getLocationRoute​

Retrieves a specific location by ID via GET /locations/:locationId with public access.

Purpose: Provides public access to location data retrieval with proper validation and error handling for specific location lookup by ID.

Route Details:

  • Method: GET
  • Path: /locations/:locationId
  • Authentication: Not required (public access)

Blocks: getLocationById

Validators: None (public access)

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.getLocationRoute);

updateLocationRoute​

Updates an existing location via PATCH /locations/:locationId with admin authentication.

Purpose: Handles location update requests with partial field modifications, proper validation, and response with updated location data.

Route Details:

  • Method: PATCH
  • Path: /locations/:locationId
  • Authentication: Required (Bearer token)

Blocks: updateLocation, getLocationById

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.updateLocationRoute);

deleteLocationRoute​

Deletes a location and its descendants via DELETE /locations/:locationId with admin authentication.

Purpose: Handles location deletion requests with comprehensive descendant validation to prevent orphaned child locations, ensuring data integrity in the location hierarchy structure.

Route Details:

  • Method: DELETE
  • Path: /locations/:locationId
  • Authentication: Required (Bearer token)

Blocks: buildDescendantsFilter, findLocations, assertNoDescendantLocations, deleteLocation

Validators: isAuthenticated, checkIdentityType(['admin'])

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.deleteLocationRoute);

findLocationsRoute​

Retrieves locations with pagination and filtering via GET /locations with public access.

Purpose: Provides a public endpoint for searching and listing locations with pagination support, enabling efficient browsing and filtering of location data.

Route Details:

  • Method: GET
  • Path: /locations
  • Authentication: Not required (public access)

Blocks: findLocations, withPagination (built-in pagination wrapper)

Validators: None (public access)

Usage:

import { routes } from '@nodeblocks/backend-sdk';

// Register route with Express app
app.use('/api', routes.findLocationsRoute);

🔗 Related Documentation​