ForSURE.categorylist.models.revision

Revision model for the categorylist database.

Revision Module

The Revision module provides API endpoints for managing revisions within categorylist versions. Revisions are working copies where you can make changes to your categorylist structure and data before publishing.

Overview

Revisions are the working units of a categorylist. Each revision:

  • Belongs to a version
  • Has a number (sequential within the version)
  • Can be a draft (work in progress) or published
  • Contains labels (column definitions) and items (product data)
  • Can have a base revision (for incremental updates)

Revisions allow you to:

  • Work on changes without affecting published data
  • Create multiple drafts
  • Publish revisions when ready
  • Build on top of previous revisions

Main Use Cases

1. Get Revision

Retrieve a complete revision with all its data:

  • Revision metadata
  • Labels (column definitions)
  • Associated items and features

Endpoint: GET /revisions/{revision_uuid}

2. Create Revision

Create a new revision within a version:

  • Can be based on an existing revision
  • Starts as a draft
  • Can specify a name

Endpoint: POST /revisions

3. Update Revision

Modify revision properties:

  • Update revision name
  • Change draft status
  • Update metadata

Endpoint: PUT /revisions/{revision_uuid}

4. Publish Revision

Publish a draft revision:

  • Makes the revision available for use
  • Cannot be modified after publishing (create new revision for changes)

Endpoint: POST /revisions/{revision_uuid}/publish

5. Upload Data

Bulk upload items to a revision:

  • Upload CSV files
  • Import large datasets
  • Map columns automatically

Endpoint: POST /revisions/{revision_uuid}/upload

Revision Lifecycle

Draft Revision → Work on Changes → Publish → (Read-only)
                                      ↓
                              Create New Draft Revision
  1. Draft: Working copy where you can make changes
  2. Published: Finalized revision, cannot be modified
  3. New Draft: Create a new draft based on published revision for further changes

Base Revisions

Revisions can have a base revision, which allows:

  • Incremental updates (only changes are stored)
  • Merging data from base and current revision
  • Efficient storage of changes

Key Features

  • Draft System: Work on changes without affecting published data
  • Bulk Upload: Import large datasets via CSV
  • Base Revisions: Build incrementally on previous revisions
  • Publishing: Finalize revisions when ready
  • Metadata Tracking: Track who created/updated revisions and when

Permissions

All endpoints require the CATEGORYLIST_SUGGEST-EDIT permission, except publishing which may require additional permissions.

  • Version: Revisions belong to versions
  • Items: Items are stored in revisions
  • Labels: Column definitions are stored in revisions
  • Features: Item features are associated with revisions