Skip to content

api-contract.md

Latest commit

 

History

History
320 lines (256 loc) · 5.95 KB

api-contract.md

File metadata and controls

320 lines (256 loc) · 5.95 KB

Orbito API Contract

Overview

This document defines the REST API contract between the Backend Platform and other Orbito components (React SDK and Browser Extension).

Base URL: http://localhost:8001/api/v1

Authentication

All API requests require an API key in the header:

X-API-Key: <website_api_key>

Data Types

UUID Format

All IDs use UUID v4 format (string):

"550e8400-e29b-41d4-a716-446655440000"

Timestamps

ISO 8601 format with UTC timezone:

"2025-01-15T10:30:00.000Z"

Endpoints

1. Register Website

Endpoint: POST /api/v1/websites/register

Description: Register a new website to get an API key for action registration.

Request Headers:

{
  "Content-Type": "application/json"
}

Request Body:

{
  "domain": "example.com",
  "owner_email": "owner@example.com",
  "website_name": "Example Website"
}

Response (201 Created):

{
  "website_id": "550e8400-e29b-41d4-a716-446655440000",
  "domain": "example.com",
  "api_key": "orbito_key_abc123def456",
  "created_at": "2025-01-15T10:30:00.000Z"
}

Error Responses:

  • 400 Bad Request: Invalid domain or missing fields
  • 409 Conflict: Domain already registered

2. Register Action (SDK → Backend)

Endpoint: POST /api/v1/actions/register

Description: Register or update an action from the React SDK.

Request Headers:

{
  "Content-Type": "application/json",
  "X-API-Key": "orbito_key_abc123def456"
}

Request Body:

{
  "action_id": "add-to-cart-button",
  "intent": "addToCart",
  "description": "Adds the current product to the shopping cart",
  "selector": "[data-orbito-id='add-to-cart-button']",
  "parameters": {
    "quantity": {
      "type": "number",
      "required": false,
      "default": 1,
      "description": "Number of items to add"
    },
    "productId": {
      "type": "string",
      "required": true,
      "description": "Product identifier"
    }
  },
  "position": {
    "x": 450,
    "y": 320
  },
  "metadata": {
    "component_type": "button",
    "page_path": "/product/123"
  }
}

Response (200 OK):

{
  "success": true,
  "action_id": "add-to-cart-button",
  "registered_at": "2025-01-15T10:30:00.000Z"
}

Error Responses:

  • 401 Unauthorized: Invalid or missing API key
  • 400 Bad Request: Invalid action schema
  • 429 Too Many Requests: Rate limit exceeded

3. Discover Actions (Extension → Backend)

Endpoint: GET /api/v1/actions

Description: Get all available actions for a website domain.

Query Parameters:

  • domain (required): Website domain (e.g., "example.com")
  • is_active (optional): Filter by active status (default: true)

Request Headers:

{
  "Content-Type": "application/json"
}

Example Request:

GET /api/v1/actions?domain=example.com&is_active=true

Response (200 OK):

{
  "domain": "example.com",
  "actions": [
    {
      "action_id": "add-to-cart-button",
      "intent": "addToCart",
      "description": "Adds the current product to the shopping cart",
      "selector": "[data-orbito-id='add-to-cart-button']",
      "parameters": {
        "quantity": {
          "type": "number",
          "required": false,
          "default": 1,
          "description": "Number of items to add"
        },
        "productId": {
          "type": "string",
          "required": true,
          "description": "Product identifier"
        }
      },
      "position": {
        "x": 450,
        "y": 320
      },
      "is_active": true,
      "usage_count": 42,
      "last_used": "2025-01-15T09:15:00.000Z"
    }
  ],
  "total_count": 1
}

Error Responses:

  • 404 Not Found: Domain not registered
  • 400 Bad Request: Invalid query parameters

4. Get Website Details

Endpoint: GET /api/v1/websites/{website_id}

Description: Get details of a registered website.

Request Headers:

{
  "X-API-Key": "orbito_key_abc123def456"
}

Response (200 OK):

{
  "website_id": "550e8400-e29b-41d4-a716-446655440000",
  "domain": "example.com",
  "website_name": "Example Website",
  "owner_email": "owner@example.com",
  "created_at": "2025-01-15T10:30:00.000Z",
  "total_actions": 15,
  "active_actions": 12
}

5. Update Action Status

Endpoint: PATCH /api/v1/actions/{action_id}/status

Description: Enable or disable an action.

Request Headers:

{
  "Content-Type": "application/json",
  "X-API-Key": "orbito_key_abc123def456"
}

Request Body:

{
  "is_active": false
}

Response (200 OK):

{
  "success": true,
  "action_id": "add-to-cart-button",
  "is_active": false,
  "updated_at": "2025-01-15T10:30:00.000Z"
}

6. Increment Action Usage

Endpoint: POST /api/v1/actions/{action_id}/usage

Description: Increment usage counter when action is executed (called by SDK after successful execution).

Request Headers:

{
  "X-API-Key": "orbito_key_abc123def456"
}

Response (200 OK):

{
  "success": true,
  "usage_count": 43
}

Error Response Format

All error responses follow this structure:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {}
  }
}

Error Codes

  • INVALID_API_KEY: API key is missing or invalid
  • DOMAIN_NOT_FOUND: Requested domain not registered
  • ACTION_NOT_FOUND: Action ID doesn't exist
  • INVALID_SCHEMA: Request body doesn't match expected schema
  • RATE_LIMIT_EXCEEDED: Too many requests
  • DOMAIN_ALREADY_EXISTS: Domain already registered

Rate Limits

  • Action Registration: 100 requests per minute per API key
  • Action Discovery: 60 requests per minute per IP
  • Website Registration: 10 requests per hour per IP

CORS Configuration

Backend must allow:

  • Origins: All domains (for extension)
  • Methods: GET, POST, PATCH, DELETE, OPTIONS
  • Headers: Content-Type, X-API-Key