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