Utils Routes

← Back to Documentation Home

Table of Contents

1. Sort Items

Sort Items

Move an item to a specific position in a sortable collection.

• URL: /utils/sort/:collection
• Method: POST
• Auth required: Yes
• Permissions required: Update permission for the collection's "sort" field

URL Parameters

Request Body

{
  "item": "550e8400-e29b-41d4-a716-446655440000",
  "to": "550e8400-e29b-41d4-a716-446655440001",
  "mode": "after"
}

Mode Behavior

Success Response

• Code: 200 OK
• Content:

{
  "data": {
    "item": "550e8400-e29b-41d4-a716-446655440000",
    "collection": "products"
  }
}

Error Responses

• Code: 400 Bad Request

  • Content: { "error": { "message": "Missing item ID to sort" } }
  • Content: { "error": { "message": "Missing target ID to sort to" } }
  • Content: { "error": { "message": "Collection 'collection_name' does not have a sort field" } }

• Code: 401 Unauthorized

  • Content: { "error": { "message": "Authentication required" } }

• Code: 403 Forbidden

  • Content: { "error": { "message": "You don't have permission to sort items in 'collection_name'" } }

• Code: 404 Not Found

  • Content: { "error": { "message": "Collection 'collection_name' does not exist" } }
  • Content: { "error": { "message": "Item with ID {id} not found" } }
  • Content: { "error": { "message": "Target item with ID {id} not found" } }

• Code: 500 Internal Server Error

  • Content: { "error": { "message": "Error message" } }

Notes

• The collection must have a sort field defined in its schema.
• To enable sorting functionality for a collection, set sortEnabled: true in the collection's schema.
• When an item is moved, all items with sort values greater than or equal to the target position are shifted to make room for the moved item.
• The sort endpoint uses database transactions to ensure consistency.

Example Usage

// Move product with ID 123 BEFORE product with ID 456 (default behavior)
fetch('/utils/sort/products', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    item: 123,
    to: 456,
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error:', error));

// Move product with ID 123 AFTER product with ID 456
fetch('/utils/sort/products', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    item: 123,
    to: 456,
    mode: 'after',
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error:', error));

Related Documentation

• Item Routes - CRUD operations for your data
• Schema Reference Guide - Data model definitions
• API Routes Reference - Complete list of all API endpoints

← Back to Documentation Home