Skip to content

backend-api-reference.md

Latest commit

 

History

History
188 lines (136 loc) · 4.03 KB

backend-api-reference.md

File metadata and controls

188 lines (136 loc) · 4.03 KB
Raw

Backend API Reference

This document describes the HTTP API surface exposed by the frontend backend (src/app/api). The routes are intentionally thin stubs in the current code base; they exist primarily for analytics hooks and development/testing.

Each entry includes the HTTP method, path, expected request body (if any), and an example response. All endpoints return JSON.

Standard Response Conventions

All endpoints follow these conventions.

Success Response

{
  "success": true,
  "data": { ... },
  "meta": { ... }       // optional pagination / additional metadata
}

Error Response

{
  "success": false,
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Too many requests. Please try again later.",
    "retryAfterSeconds": 60  // present on 429 and 503 only
  }
}

Rate Limited Responses (429 / 503)

When a request is rate-limited, the response includes the Retry-After HTTP header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Status retryAfterSeconds default Meaning
429 60 s Client exceeded rate limit
503 30 s Service temporarily unavailable

Clients should wait the indicated seconds before retrying. See error-handling.md for the full client retry strategy (exponential backoff + jitter).

POST /api/commitments

Creates a new commitment. In the stub implementation, no persistence occurs; this route is mainly used to log CommitmentCreated analytics events.

  • Request body: arbitrary JSON with commitment parameters (amount, term, etc.)
  • Response: stub message with the requester IP.

Example

curl -X POST http://localhost:3000/api/commitments \
     -H 'Content-Type: application/json' \
     -d '{"asset":"XLM","amount":100}'
{
  "message": "Commitments creation endpoint stub - rate limiting applied",
  "ip": "::1"
}

POST /api/commitments/[id]/settle

Marks the commitment identified by id as settled. Currently a stub that emits CommitmentSettled events.

  • Path parameter: id (string)
  • Request body: optional JSON payload with additional details.
  • Response: stub confirmation message.

Example

curl -X POST http://localhost:3000/api/commitments/abc123/settle \
     -H 'Content-Type: application/json' \
     -d '{"finalValue":105}'
{
  "message": "Stub settlement endpoint for commitment abc123",
  "commitmentId": "abc123"
}

POST /api/commitments/[id]/early-exit

Triggers an early exit (with penalty) for the named commitment. Emits CommitmentEarlyExit events.

  • Path parameter: id (string)
  • Request body: optional JSON with penalty or reason.
  • Response: stub message.

Example

curl -X POST http://localhost:3000/api/commitments/abc123/early-exit \
     -H 'Content-Type: application/json' \
     -d '{"reason":"user-request"}'
{
  "message": "Stub early-exit endpoint for commitment abc123",
  "commitmentId": "abc123"
}

POST /api/attestations

Records an attestation event. Stub implementation logs AttestationReceived.

  • Request body: JSON describing the attestation (e.g. signature, commitmentId).
  • Response: stub message with requester IP.

Example

curl -X POST http://localhost:3000/api/attestations \
     -H 'Content-Type: application/json' \
     -d '{"commitmentId":"abc123","status":"valid"}'
{
  "message": "Attestations recording endpoint stub - rate limiting applied",
  "ip": "::1"
}

GET /api/metrics

Simple health/metrics endpoint used by monitoring tools.

  • Response: JSON object containing uptime, mock request/error counts, and current timestamp.

Example

curl http://localhost:3000/api/metrics
{
  "status": "up",
  "uptime": 123.456,
  "mock_requests_total": 789,
  "mock_errors_total": 2,
  "timestamp": "2026-02-25T00:00:00.000Z"
}

🔧 This reference will grow as the backend implements real business logic.