chore: import upstream snapshot with attribution

apps/opik-documentation/python-sdk-docs/source/rest_api/overview.rst

@@ -0,0 +1,147 @@
+REST API Overview
+=================
+
+The Opik SDK provides direct access to the underlying REST API client through the ``rest_client`` property.
+This allows advanced users to make direct API calls when needed, providing full access to all Opik platform functionality.
+
+.. warning::
+   The REST client is not guaranteed to be backward compatible with future SDK versions.
+   While it provides a convenient way to use the current REST API of Opik,
+   it's not considered safe to heavily rely on its API as Opik's REST API contracts may change.
+
+When to Use the REST API
+------------------------
+
+The REST API is useful when you need to:
+
+* Perform operations not available in the high-level SDK
+* Build custom integrations or tools
+* Access advanced filtering or querying capabilities
+* Implement batch operations for performance
+* Work with raw API responses for specific use cases
+
+Getting Started
+---------------
+
+To access the REST client, first create an Opik instance and then use the ``rest_client`` property:
+
+.. code-block:: python
+
+   import opik
+
+   # Initialize Opik client
+   client = opik.Opik()
+   
+   # Access REST API through the rest_client property
+   rest_client = client.rest_client
+
+Basic Examples
+--------------
+
+Here are some common patterns for using the REST API:
+
+**Working with Traces**
+
+.. code-block:: python
+
+   # Get a specific trace
+   trace = client.rest_client.traces.get_trace_by_id("trace-id")
+   
+   # Search for traces with filters
+   traces = client.rest_client.traces.search_traces(
+       project_name="my-project",
+       filters=[{
+           "field": "name",
+           "operator": "contains",
+           "value": "important"
+       }],
+       max_results=100
+   )
+
+**Managing Datasets**
+
+.. code-block:: python
+
+   # List all datasets
+   datasets = client.rest_client.datasets.find_datasets(
+       page=0,
+       size=20
+   )
+   
+   # Create a new dataset
+   dataset = client.rest_client.datasets.create_dataset(
+       name="my-dataset",
+       description="A test dataset"
+   )
+   
+   # Add items to the dataset
+   items = [
+       {
+           "input": {"question": "What is AI?"},
+           "expected_output": {"answer": "Artificial Intelligence"}
+       }
+   ]
+   client.rest_client.datasets.create_or_update_dataset_items(
+       dataset_id=dataset.id,
+       items=items
+   )
+
+**Running Experiments**
+
+.. code-block:: python
+
+   # Create an experiment
+   experiment = client.rest_client.experiments.create_experiment(
+       name="my-experiment",
+       dataset_name="my-dataset"
+   )
+   
+   # Add experiment results
+   client.rest_client.experiments.create_experiment_items(
+       experiment_id=experiment.id,
+       items=[{
+           "dataset_item_id": "item-id",
+           "trace_id": "trace-id",
+           "output": {"result": "success"}
+       }]
+   )
+
+Response Types and Pagination
+------------------------------
+
+Most list operations return paginated results with a consistent structure:
+
+.. code-block:: python
+
+   # Example paginated response structure
+   response = client.rest_client.datasets.find_datasets(page=0, size=10)
+   
+   # Access the data
+   datasets = response.content  # List of dataset objects
+   total_count = response.total  # Total number of items
+   current_page = response.page  # Current page number
+   page_size = response.size     # Items per page
+
+Error Handling
+--------------
+
+The REST API raises specific exceptions for different error conditions:
+
+.. code-block:: python
+
+   from opik.rest_api.core.api_error import ApiError
+   
+   try:
+       trace = client.rest_client.traces.get_trace_by_id("invalid-id")
+   except ApiError as e:
+       if e.status_code == 404:
+           print("Trace not found")
+       else:
+           print(f"API error: {e.status_code} - {e.body}")
+
+Next Steps
+----------
+
+* Browse the :doc:`clients/index` for detailed API reference
+* See :doc:`objects` for data type documentation
+* Check the main SDK documentation for higher-level operations