From 638b68214b095c9695e1d26c10e62c6cdddcbb2f Mon Sep 17 00:00:00 2001
From: claudi <claudius.hansch@hoerl-im.de>
Date: Wed, 25 Mar 2026 08:20:50 +0100
Subject: [PATCH] docs: Update README and module docstrings to clarify legacy
 API usage and CRUD operations in Elytra PIM Web API

---
 elytra_client/rest_api/README.md          | 14 +++++++---
 elytra_client/rest_api/__init__.py        | 14 +++++++++-
 elytra_client/rest_api/client/__init__.py | 32 +++++++++--------------
 3 files changed, 37 insertions(+), 23 deletions(-)

diff --git a/elytra_client/rest_api/README.md b/elytra_client/rest_api/README.md
index 215d6ba..12c2fbf 100644
--- a/elytra_client/rest_api/README.md
+++ b/elytra_client/rest_api/README.md
@@ -1,11 +1,19 @@
 # Lobster PIM Legacy REST API Client
 
-This subpackage provides a Python client for accessing the legacy REST API of Lobster PIM (Product Information Management system). It offers access to scheduled jobs and protocol logs through a clean, Pydantic-based interface.
+This subpackage provides a Python client for accessing the **legacy REST API** of Lobster PIM (now called Elytra).
+
+## ⚠️ Important: Legacy API vs. New Web API
+
+The Lobster REST API is the **legacy API** that provides read-only access to:
+- **Scheduled Jobs** (`/rest/job/*`) - Job execution and monitoring
+- **Protocol Logs** (`/rest/protocol/*`) - Execution logs and protocol information
+
+**For CRUD operations** on products, product groups, attributes, media, and other resources in the new Elytra PIM Web API, use the [`ElytraClient`](../client.py) with the OpenAPI-based Web API instead.
 
 ## Features
 
-- **Job Management**: Access, monitor, and execute scheduled jobs
-- **Protocol/Log Access**: Retrieve execution logs and protocol information
+- **Job Management**: Get, monitor, and execute scheduled jobs (read-only)
+- **Protocol/Log Access**: Retrieve execution logs and protocol information (read-only)
 - **Authentication**: Support for both username/password and API token authentication
 - **Job Control**: Execute jobs with parameter overrides and queue management
 - **Type Safety**: Full Pydantic model validation for all API responses
diff --git a/elytra_client/rest_api/__init__.py b/elytra_client/rest_api/__init__.py
index 93f4111..bbbcf1f 100644
--- a/elytra_client/rest_api/__init__.py
+++ b/elytra_client/rest_api/__init__.py
@@ -1,4 +1,11 @@
-"""Lobster PIM Legacy REST API client and utilities"""
+"""Lobster PIM Legacy REST API client and utilities
+
+This module provides access to the legacy Lobster REST API, which offers
+read-only access to Scheduled Jobs and Protocol logs.
+
+For CRUD operations on products, product groups, attributes, media, and other
+resources in the new Elytra PIM Web API, use the ElytraClient instead.
+"""
 
 from .auth import AuthMethod, RestApiAuth
 from .client import LobsterRestApiClient
@@ -17,18 +24,23 @@ from .models import (
 )
 
 __all__ = [
+    # Authentication
     "RestApiAuth",
     "AuthMethod",
+    # Client
     "LobsterRestApiClient",
+    # Job models
     "JobInfo",
     "JobDetailInfo",
     "JobOverviewResponse",
     "JobExecutionResponse",
     "JobControlRequest",
     "JobControlResponse",
+    # Protocol models
     "ProtocolInfo",
     "ProtocolListResponse",
     "ProtocolCategoryInfo",
     "ProtocolCategoryListResponse",
+    # Error model
     "ErrorResponse",
 ]
diff --git a/elytra_client/rest_api/client/__init__.py b/elytra_client/rest_api/client/__init__.py
index eef7e3d..c33ab6b 100644
--- a/elytra_client/rest_api/client/__init__.py
+++ b/elytra_client/rest_api/client/__init__.py
@@ -1,34 +1,25 @@
 """Lobster PIM Legacy REST API Client."""
 
-from .attribute_groups import AttributeGroupsMixin
-from .attributes import AttributesMixin
 from .base import LobsterRestApiClientBase
 from .jobs import JobsMixin
-from .media import MediaMixin
-from .product_groups import ProductGroupsMixin
-from .products import ProductsMixin
 from .protocols import ProtocolsMixin
-from .text import TextMixin
-from .tree_groups import TreeGroupsMixin
 
 
 class LobsterRestApiClient(
     LobsterRestApiClientBase,
     JobsMixin,
     ProtocolsMixin,
-    ProductsMixin,
-    ProductGroupsMixin,
-    TreeGroupsMixin,
-    AttributesMixin,
-    AttributeGroupsMixin,
-    MediaMixin,
-    TextMixin,
 ):
     """
-    Complete client for the Lobster PIM Legacy REST API.
+    Legacy REST API client for the Lobster PIM system.
 
-    Combines base infrastructure with domain-specific mixins for organized
-    access to all API endpoints across jobs, protocols, products, media, etc.
+    Provides read-only access to Scheduled Jobs and Protocol logs via the
+    Lobster REST API endpoints. Only supports GET operations on:
+    - Scheduled Jobs (/rest/job/*)
+    - Protocols (/rest/protocol/*)
+
+    The new Elytra PIM Web API (for CRUD operations on products, groups,
+    attributes, media, etc.) should use the ElytraClient instead.
 
     Example:
         >>> from elytra_client.rest_api.client import LobsterRestApiClient
@@ -37,10 +28,13 @@ class LobsterRestApiClient(
         >>> auth = RestApiAuth.from_bearer_token("your-token")
         >>> client = LobsterRestApiClient("http://localhost:8080", auth)
         >>>
-        >>> # Access jobs
+        >>> # Access jobs (read-only)
         >>> jobs = client.get_all_active_jobs()
+        >>> job_detail = client.get_job_detail(job_id=172475107)
+        >>>
+        >>> # Access protocols (read-only)
         >>> protocols = client.get_protocols()
-        >>> products = client.get_all_products()
+        >>> protocol = client.get_protocol(protocol_id="176728573")
     """
 
     pass