Locations API

Manage location hierarchies and organizational structure

Overview

The Locations API enables management of hierarchical location structures within containers. Locations can be nested to create organizational hierarchies, allowing for precise tracking of where inventory items are stored.

Endpoints

Get Locations

Retrieves all locations associated with a specific container.

GET /containers/{containerId}/locations

Path Parameters

containerId · integer · required

The ID of the container whose locations to retrieve

Response

data · Location[]

Array of location objects

Show Location Object

id · integer

Unique identifier for the location

name · string

Display name of the location

description · string

Optional description of the location

containerId · integer

ID of the parent container

parentId · integer

ID of the parent location (null for root locations)

children · Location[]

Nested array of child locations (hierarchical structure)

Example Request

const response = await fetch('/containers/42/locations', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const { data } = await response.json();

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Warehouse A",
      "description": "Main warehouse facility",
      "containerId": 42,
      "parentId": null,
      "children": [
        {
          "id": 2,
          "name": "Shelf 1",
          "description": "First shelf in warehouse",
          "containerId": 42,
          "parentId": 1,
          "children": []
        }
      ]
    }
  ]
}

Error Responses

401 · error

Unauthorized - Authentication required or token invalid

404 · error

Container not found

---

Create Location

Creates a new location within a container.

POST /locations

Request Body

container_id · integer · required

ID of the container to create the location in

name · string · required

Name of the location

description · string

Optional description of the location

parent_id · integer

ID of the parent location (omit for root-level location)

Response

data · Location

The newly created location object

Example Request

const response = await fetch('/locations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    container_id: 42,
    name: 'Warehouse B',
    description: 'Secondary storage facility',
    parent_id: null
  })
});

const { data } = await response.json();

Example Response

{
  "data": {
    "id": 5,
    "name": "Warehouse B",
    "description": "Secondary storage facility",
    "containerId": 42,
    "parentId": null
  }
}

Error Responses

201 · success

Location created successfully

401 · error

Unauthorized - Invalid or missing authentication token

400 · error

Bad request - Invalid parent_id or missing required fields

---

Update Location

Updates an existing location’s details.

PATCH /locations/{locationId}

Path Parameters

locationId · integer · required

The ID of the location to update

Request Body

name · string · required

Updated name of the location

description · string

Updated description

parent_id · integer

Updated parent location ID (use null to make it a root location)

Response

data · Location

The updated location object

Example Request

const response = await fetch('/locations/5', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Warehouse B - Expanded',
    description: 'Expanded secondary storage facility',
    parent_id: null
  })
});

const { data } = await response.json();

Example Response

{
  "data": {
    "id": 5,
    "name": "Warehouse B - Expanded",
    "description": "Expanded secondary storage facility",
    "containerId": 42,
    "parentId": null
  }
}

Error Responses

200 · success

Location updated successfully

401 · error

Unauthorized - Authentication required

404 · error

Location not found

400 · error

Bad request - Invalid parent_id (would create circular hierarchy)

---

Delete Location

Deletes a location from the system.

DELETE /locations/{locationId}

Path Parameters

locationId · integer · required

The ID of the location to delete

Response

Returns status code 204 (No Content) or 200 (OK) on successful deletion.

Example Request

const response = await fetch('/locations/5', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

if (response.status === 204) {
  console.log('Location deleted successfully');
}

Error Responses

204 · success

Location deleted successfully (no content returned)

200 · success

Location deleted successfully

401 · error

Unauthorized - Authentication required

404 · error

Location not found

409 · error

Conflict - Cannot delete location with child locations or assigned items

---

Business Logic Notes

Hierarchical Structure

• Locations support unlimited nesting depth through the parent_id field
• The children array is populated recursively when retrieving locations
• Root-level locations have parent_id set to null

Deletion Rules

• Locations with child locations must have children removed first
• Locations with assigned inventory items cannot be deleted until items are reassigned
• Consider implementing soft deletes for audit trail purposes

Performance Considerations

• The children array is not included in toJson() to prevent circular serialization issues
• For deep hierarchies, consider implementing pagination or lazy loading of child locations
• The getLocationsCount() method fetches all locations and returns the count - consider server-side counting for large datasets

Access Control

• All location operations require valid JWT authentication
• Users can only access locations within containers they have permission to view
• Container ownership determines location management permissions