Skip to content

API_ENDPOINTS.md

Latest commit

 

History

History
441 lines (324 loc) · 8.87 KB

API_ENDPOINTS.md

File metadata and controls

441 lines (324 loc) · 8.87 KB
Raw

API Endpoints

This document describes the REST API endpoints for the Reputation System. All endpoints follow the standards in API_STANDARDS.md for:

  • Required headers (authentication, request ID, content type)
  • Standard response and error formats
  • HTTP status codes
  • Rate limiting and headers
  • CORS policy
  • Pagination, filtering, and sorting conventions

See API_STANDARDS.md for all global conventions.

Table of Contents

  1. Snapshots

  2. Workflows

  3. Strategies

  4. Scores

  5. Onchain Commitment

  6. Analytics

  7. Authentication

  8. Health & Monitoring

  9. Error Handling

  10. Versioning

1. Snapshots

List Snapshots

  • GET /api/v1/snapshots
  • Description: List all snapshots (optionally filter by status, date, etc.)
  • Query Parameters: status, created_at, page, size, sort
  • Response:
[
  {
    "id": "snap_123",
    "name": "Q1 2025 Governance Snapshot",
    "status": "draft",
    "created_at": "2025-06-01T12:00:00Z"
  }
]

Create Snapshot

  • POST /api/v1/snapshots
  • Description: Create a new snapshot with configuration and strategies.
  • Request:
{
  "name": "Q1 2025 Governance Snapshot",
  "strategies": [
    {
      "strategy": {
        "name": "token-weighted-voting",
        "version": "1.0.0"
      },
      "weight": 1.0,
      "parameters": {
        "start_block": 0,
        "end_block": 12345678,
        "min_balance": 100
      }
    }
  ]
}
  • Response:
{
  "id": "snap_123",
  "status": "draft"
}

Get Snapshot Details

  • GET /api/v1/snapshots/{snapshot_id}
  • Description: Get details of a specific snapshot.
  • Response:
{
  "id": "snap_123",
  "name": "Q1 2025 Governance Snapshot",
  "status": "draft",
  "created_at": "2025-06-01T12:00:00Z",
  "strategies": [ ... ]
}

Update Snapshot

  • PATCH /api/v1/snapshots/{snapshot_id}
  • Description: Update snapshot configuration (only if in draft state).
  • Request: (partial update)
{
  "name": "Q1 2025 Governance Snapshot - Updated"
}

Delete Snapshot

  • DELETE /api/v1/snapshots/{snapshot_id}
  • Description: Delete a snapshot (only if in draft state).

Consent Management (DDI Redirect)

  • GET /api/v1/snapshots/{snapshot_id}/consent
  • Description: Returns a redirect URL to the DDI platform for managing consent for the specified snapshot. After generating a consent link, strategies for the snapshot are locked. Changing strategies after this point will invalidate all previous consents and require generating a new consent link and collecting new consents.
  • Response:
{
  "ddi_consent_url": "https://ddi.example.com/consent?snapshot_id=snap_123"
}

2. Workflows

List Workflows for Snapshot

  • GET /api/v1/workflows
  • Description: List all workflows. Can by filtered by snapshot id

Start Workflow

  • POST /api/v1/snapshots/{snapshot_id}/run
  • Description: Start a new workflow execution for a snapshot.
  • Response:
{
  "workflow_id": "work_123",
  "status": "running"
}

Get Workflow Status

  • GET /api/v1/workflows/{workflow_id}
  • Description: Get status and progress of a workflow.
  • Response:
{
  "workflow_id": "work_123",
  "status": "completed",
  "progress": 1.0,
  "started_at": "2025-06-01T12:00:00Z",
  "finished_at": "2025-06-01T12:30:00Z"
}

3. Strategies

List Available Strategies

  • GET /api/v1/strategies
  • Description: List all available strategy types and versions.
  • Response:
[
  {
    "name": "token-weighted-voting",
    "version": "1.0.0",
    "description": "Voting power proportional to token holdings."
  }
]

4. Scores

Get Scores for Snapshot

  • GET /api/v1/snapshots/{snapshot_id}/scores
  • Description: Get all scores for a snapshot (paginated, may require role-based access).
  • Query Parameters: page, size, sort
  • Response:
[
  {
    "sub_id": "0x123...",
    "weighted_score": 0.87,
    "strategy_scores": [ ... ]
  }
]

Get Score for Subject

  • GET /api/v1/snapshots/{snapshot_id}/scores/{sub_id}
  • Description: Get the score details for a specific subject in a snapshot.

5. Onchain Commitment

Commit Snapshot Onchain

  • POST /api/v1/snapshots/{snapshot_id}/commit
  • Description: Commit the results of a workflow to the blockchain (only allowed by authorized user, only once per snapshot).
  • Request:
{
  "workflow_id": "work_123"
}
  • Response:
{
  "transaction": "0xabc...",
  "block_number": 12345678,
  "merkle_root": "0xdeadbeef..."
}

Get Commitment Details

  • GET /api/v1/snapshots/{snapshot_id}/commit
  • Description: Get onchain commitment details for a snapshot.

Generate Merkle Proof

  • GET /api/v1/snapshots/{snapshot_id}/scores/{sub_id}/merkle-proof
  • Description: Get a Merkle proof for a subject's score in a snapshot.
  • Response:
{
  "merkle_proof": ["0x...", "0x..."],
  "merkle_root": "0xdeadbeef..."
}

6. Analytics

Get Score Distribution

  • GET /api/v1/snapshots/{snapshot_id}/analytics/score-distribution?strategy={strategy}
  • Description: Get histogram/bucketed distribution of scores for a strategy and snapshot.
  • Response:
{
  "score_distribution": {
    "0-0.1": 12,
    "0.1-0.2": 34,
    // ...
    "0.9-1.0": 8
  }
}

Get Average/Median Score

  • GET /api/v1/snapshots/{snapshot_id}/analytics/summary?strategy={strategy}
  • Description: Get average and median score for a strategy and snapshot.
  • Response:
{
  "average_score": 0.42,
  "median_score": 0.38
}

Get Anonymized Leaderboard

  • GET /api/v1/snapshots/{snapshot_id}/analytics/leaderboard?strategy={strategy}
  • Description: Get anonymized leaderboard for a strategy and snapshot.
  • Response:
{
  "leaderboard": [
    { "rank": 1, "score": 0.98 },
    { "rank": 2, "score": 0.95 },
    // ...
    { "rank": 10, "score": 0.87 }
  ]
}

Get Participation Rate

  • GET /api/v1/snapshots/{snapshot_id}/analytics/participation?strategy={strategy}
  • Description: Get participation rate (percentage of users with nonzero scores) for a strategy and snapshot.
  • Response:
{
  "participation_rate": 0.73
}

Note: Analytics endpoints apply differential privacy to user-level queries to protect individual privacy.

7. Authentication

Obtain JWT Token

  • POST /api/v1/auth/token
  • Description: Obtain a JWT token using DDI or other authentication provider.
  • Request:
{
  "ddi_token": "..."
}
  • Response:
{
  "jwt": "...",
  "refresh_token": "...",
  "expires_in": 3600
}

Refresh JWT Token

  • POST /api/v1/auth/refresh
  • Description: Obtain a new JWT token using a refresh token.
  • Request:
{
  "refresh_token": "..."
}
  • Response:
{
  "jwt": "...",
  "refresh_token": "...",
  "expires_in": 3600
}

8. Health & Monitoring

Health Check

  • GET /api/v1/healthz
  • Description: Check API and service health.
  • Response:
{
  "status": "ok"
}

Metrics

  • GET /api/v1/metrics
  • Description: Expose Prometheus-compatible metrics for monitoring (protected endpoint).

9. Error Handling

All endpoints follow the error response format in API_STANDARDS.md.

10. Versioning

All endpoints are versioned under /api/v1/ and may be incremented as the API evolves.