helixml / apps-client

Client-Server Interaction

This document outlines the client-server interaction for the HelixML Apps Client library (https://github.com/helixml/apps-client/).

API Endpoints

The client library interacts with the Helix Cloud backend using a set of API endpoints. These endpoints are used for various actions, such as running scripts, fetching data, and managing projects.

runScript Endpoint:

  • Purpose: Executes a script in the Helix Cloud environment.
  • URL: /api/v1/scripts/run
  • Method: POST
  • Request Payload:
    • script: The script code to be executed.
    • inputs: A dictionary of input parameters for the script.
    • project_id: The ID of the project to which the script belongs.
  • Response Payload:
    • output: The output generated by the script execution.
    • status: The execution status (e.g., “success”, “error”).
    • errors: A list of errors encountered during execution.
  • Example Request (JSON):
    {
              "script": "print('Hello, world!')",
              "inputs": {
                  "name": "John Doe"
              },
              "project_id": "1234567890"
          }

fetchData Endpoint:

  • Purpose: Retrieves data from a specified data source.
  • URL: /api/v1/data/fetch
  • Method: GET
  • Request Parameters:
    • data_source_id: The ID of the data source.
    • query: A query string for filtering and sorting data.
  • Response Payload:
    • data: A list of data items.
    • metadata: Metadata about the data source.
  • Example Request (URL):
    /api/v1/data/fetch?data_source_id=9876543210&query=name%3D%22John%20Doe%22

Authentication

The client library uses API tokens for authentication. These tokens are provided by the Helix Cloud backend and are used to authorize requests. The token is included in the Authorization header of every request.

Example Request Header:

Authorization: Bearer abcdefghijklmnopqrstuvwxyz1234567890

Error Handling

The client library handles communication errors gracefully.

Error Types:

  • Network Errors: Connection issues, timeouts.
  • Authentication Errors: Invalid or expired API tokens.
  • API Errors: Errors returned by the backend API (e.g., invalid input, script execution errors).

Error Handling Mechanisms:

  • Error Codes: API responses include HTTP status codes to indicate errors.
  • Error Messages: Detailed error messages are provided in the API response payloads.
  • Exceptions: Python exceptions are raised in the client library to signal communication errors.

Example Error Response (JSON):

{
              "error": {
                  "code": 400,
                  "message": "Invalid input: Missing script code"
              }
          }

Data Structures

The client library uses data structures to represent request and response payloads. These structures are defined using Python classes and dictionaries.

Example Request Data Structure:

class RunScriptRequest:
              def __init__(self, script, inputs, project_id):
                  self.script = script
                  self.inputs = inputs
                  self.project_id = project_id

Example Response Data Structure:

class RunScriptResponse:
              def __init__(self, output, status, errors):
                  self.output = output
                  self.status = status
                  self.errors = errors

Further Information

For more detailed information about the client library and its API endpoints, refer to the following resources: