Skip to content

api-reference.md

Latest commit

 

History

History
523 lines (407 loc) · 9.89 KB

api-reference.md

File metadata and controls

523 lines (407 loc) · 9.89 KB
Raw

API Reference — OpenBreadboard

Base URL (development): http://localhost:8000

Interactive API docs: http://localhost:8000/docs (Swagger UI)

All requests and responses use Content-Type: application/json unless noted otherwise (file upload endpoints use multipart/form-data).

Current Endpoints

These endpoints exist in the codebase today.

GET /

Returns a welcome message. Useful for confirming the API is reachable.

Request: No parameters.

Response:

{
  "message": "Welcome to OpenBreadboard API"
}

Status Codes:

Code Meaning
200 OK

GET /health

Health check endpoint. Used by load balancers and monitoring systems to confirm the service is alive.

Request: No parameters.

Response:

{
  "status": "ok"
}

Status Codes:

Code Meaning
200 Service is healthy

Planned Endpoints

These endpoints are not yet implemented. This section documents the intended API design.

Authentication

POST /auth/register

Create a new user account.

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword123",
  "display_name": "Alice"
}
Field Type Required Constraints
email string Yes Valid email format
password string Yes Min 8 characters
display_name string No Max 100 characters

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "display_name": "Alice",
  "created_at": "2025-06-01T12:00:00Z"
}

Error Responses:

Code Reason
400 Email already registered
422 Invalid request body (Pydantic validation)

POST /auth/login

Authenticate and receive a JWT access token.

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5...",
  "token_type": "bearer",
  "expires_in": 86400
}

Error Responses:

Code Reason
401 Invalid email or password

Circuits

All circuit endpoints require authentication (Authorization: Bearer <token>) unless noted.

GET /circuits

List all circuits owned by the authenticated user.

Query Parameters:

Parameter Type Default Description
page int 1 Page number
per_page int 20 Results per page (max 100)
search string — Filter by name (case-insensitive)

Response (200 OK):

{
  "total": 42,
  "page": 1,
  "per_page": 20,
  "items": [
    {
      "id": "abc123",
      "name": "LED Blinker",
      "description": "555 timer with LED",
      "component_count": 5,
      "created_at": "2025-06-01T10:00:00Z",
      "updated_at": "2025-06-02T14:30:00Z"
    }
  ]
}

POST /circuits

Create a new circuit design.

Request Body:

{
  "name": "My LED Circuit",
  "description": "A simple LED with a current-limiting resistor",
  "components": [
    {
      "id": "r1",
      "type": "resistor",
      "position": { "row": 10, "col": "A" },
      "secondary_position": { "row": 10, "col": "E" },
      "rotation": 0,
      "properties": {
        "resistance": 220,
        "unit": "Ω",
        "tolerance": "5%",
        "wattage": "0.25W"
      }
    },
    {
      "id": "d1",
      "type": "led",
      "position": { "row": 12, "col": "A" },
      "secondary_position": { "row": 12, "col": "C" },
      "rotation": 0,
      "properties": {
        "color": "red",
        "forward_voltage": 2.0,
        "max_current_ma": 20
      }
    }
  ],
  "wires": [
    {
      "id": "w1",
      "from": { "row": 10, "col": "C" },
      "to": { "row": 12, "col": "A" },
      "color": "yellow"
    }
  ]
}

Response (201 Created):

{
  "id": "new-circuit-uuid",
  "name": "My LED Circuit",
  "description": "A simple LED with a current-limiting resistor",
  "components": [...],
  "wires": [...],
  "user_id": "user-uuid",
  "created_at": "2025-06-01T12:00:00Z",
  "updated_at": "2025-06-01T12:00:00Z"
}

GET /circuits/{id}

Get a specific circuit by ID.

Path Parameters:

Parameter Type Description
id string Circuit UUID

Response (200 OK): Full circuit object (same schema as POST response)

Error Responses:

Code Reason
404 Circuit not found
403 Circuit belongs to another user

PUT /circuits/{id}

Replace a circuit's data entirely (full update).

Request Body: Same as POST /circuits

Response (200 OK): Updated circuit object

PATCH /circuits/{id}

Partially update a circuit (e.g., rename without changing components).

Request Body: Any subset of circuit fields:

{
  "name": "Updated Name",
  "description": "New description"
}

DELETE /circuits/{id}

Delete a circuit permanently.

Response (204 No Content): Empty body on success.

Simulation

POST /simulate/{circuit_id}/dc

Run a DC operating point analysis on a saved circuit.

Computes the steady-state voltage at every node and current through every branch.

Request Body:

{
  "supply_voltage": 5.0,
  "temperature": 25
}
Field Type Default Description
supply_voltage float 5.0 Power rail voltage (V)
temperature float 25 Simulation temperature (°C)

Response (200 OK):

{
  "simulation_id": "sim-uuid",
  "circuit_id": "circuit-uuid",
  "type": "dc_op",
  "status": "complete",
  "duration_ms": 120,
  "results": {
    "nodes": {
      "vcc": { "voltage": 5.0, "unit": "V" },
      "node_r1_led": { "voltage": 3.24, "unit": "V" },
      "gnd": { "voltage": 0.0, "unit": "V" }
    },
    "branches": {
      "V1": { "current": 0.0127, "unit": "A" },
      "R1": { "current": 0.0127, "unit": "A" }
    },
    "component_results": {
      "r1": {
        "voltage_drop": 1.76,
        "current": 0.0127,
        "power_mw": 22.4
      },
      "d1": {
        "voltage_drop": 2.0,
        "current": 0.0127,
        "forward_biased": true
      }
    }
  }
}

POST /simulate/{circuit_id}/transient

Run a transient (time-domain) simulation.

Returns voltage waveforms at all nodes over time. Used for RC circuits, oscillators, timer circuits.

Request Body:

{
  "step_time_ms": 0.1,
  "end_time_ms": 100.0,
  "supply_voltage": 5.0
}
Field Type Default Description
step_time_ms float 0.1 Time step for output (ms)
end_time_ms float 100 Total simulation duration (ms)
supply_voltage float 5.0 Power supply voltage (V)

Response (200 OK):

{
  "simulation_id": "sim-uuid",
  "type": "transient",
  "status": "complete",
  "duration_ms": 340,
  "results": {
    "time": [0.0, 0.1, 0.2, ...],
    "nodes": {
      "vcc": [5.0, 5.0, 5.0, ...],
      "node_cap": [0.0, 0.23, 0.44, ...]
    },
    "sample_count": 1000
  }
}

POST /simulate/{circuit_id}/ac

Run an AC frequency sweep analysis.

Returns magnitude and phase response. Used for filter circuits and amplifiers.

Request Body:

{
  "start_freq_hz": 1.0,
  "end_freq_hz": 1000000.0,
  "points_per_decade": 20
}

Response (200 OK):

{
  "type": "ac_sweep",
  "results": {
    "frequencies": [1.0, 1.26, 1.58, ...],
    "nodes": {
      "output": {
        "magnitude_db": [-3.0, -2.8, ...],
        "phase_deg": [-45.0, -40.2, ...]
      }
    }
  }
}

GET /simulate/results/{simulation_id}

Retrieve a previously run simulation result.

Response (200 OK): Same schema as the originating simulation endpoint response.

Component Library

GET /components

List all available components in the standard library.

Query Parameters:

Parameter Type Description
category string Filter by category (e.g. passive, active, ic)
search string Search by name or value

Response (200 OK):

{
  "items": [
    {
      "id": "resistor_generic",
      "name": "Resistor",
      "category": "passive",
      "symbol": "zigzag",
      "spice_model": "R",
      "parameters": [
        { "name": "resistance", "unit": "Ω", "default": 1000, "min": 1, "max": 10000000 }
      ],
      "body_color": "#e8d5a3",
      "band_colors": ["brown", "black", "red", "gold"]
    },
    {
      "id": "led_red",
      "name": "LED (Red)",
      "category": "active",
      "spice_model": "D",
      "parameters": [
        { "name": "forward_voltage", "unit": "V", "default": 2.0 },
        { "name": "max_current_ma", "unit": "mA", "default": 20 }
      ]
    }
  ]
}

Error Response Format

All errors follow a consistent format (FastAPI default):

{
  "detail": "Human-readable error message"
}

For validation errors (HTTP 422), FastAPI returns detailed field-level errors:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Rate Limiting (Planned)

Simulation endpoints will be rate-limited to prevent abuse:

Endpoint Limit
POST /simulate/*/dc 60 per minute per user
POST /simulate/*/transient 10 per minute per user
POST /simulate/*/ac 10 per minute per user

Rate limit headers will be returned:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1704067200

Versioning

API versioning is not implemented yet. When introduced, URLs will be prefixed:

  • /v1/circuits — stable v1
  • /v2/simulate — next version

Until then, breaking changes will be communicated in docs/changelog.md.