API_STANDARDS.md

Reputation System API Standards

Related Documentation:

• System Design - Core concepts and data models
• Security - Authentication and security requirements
• Operations - Performance and monitoring standards

Table of Contents

1. URL Structure
   • Format
   • Examples
   • Rules
2. Request Standards
   • Headers
   • Security Headers
   • Query Parameters
3. Response Standards
   • Standard Response Format
   • Workflow Status
   • Error Response Format
4. HTTP Status Codes
   • Success (2xx)
   • Client Error (4xx)
   • Server Error (5xx)
5. Rate Limiting
   • Limits
   • Headers
6. CORS Policy

1. URL Structure

Format

https://{HOST}/api/v{version}/{resource}[/{id}][/{sub-resource}]

Examples

• GET /api/v1/snapshots - List snapshots
• GET /api/v1/snapshots/123 - Get specific snapshot with strategies
• GET /api/v1/snapshots/123/workflows - List all workflow executions for snapshot
• POST /api/v1/snapshots/123/workflows - Execute a workflow for snapshot
• GET /api/v1/workflows/456 - Get specific workflow execution
• GET /api/v1/snapshots/123/scores - Get paginated weighted scores
• GET /api/v1/snapshots/123/scores/{subId} - Get detailed score breakdown
• GET /api/v1/snapshots/123/scores/{subId}/proof - Get Merkle proof for score
• POST /api/v1/snapshots/123/verify - Verify score against onchain commitment

Rules

• Use kebab-case: /reputation-shots, /vote-data
• Plural nouns for collections: /snapshots, /workflows
• No trailing slashes
• Consistent version prefix: /api/v1/

2. Request Standards

Headers (Required)

Content-Type: application/json
Authorization: Bearer {ddi_jwt_token}  # DDI authentication token
X-Request-ID: {uuid}                  # Request tracking

Security Headers

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Query Parameters

• Filtering: ?status=completed&strategy=governance
• Pagination: ?page=1&size=20
• Sorting: ?sort=created_at:desc

3. Response Standards

Standard Response Format

{
  "data": {
    "id": "snap_123",
    "name": "Q1 2025 Governance Snapshot",
    "status": "committed",
    "created_at": "2025-06-01T12:00:00Z",
    "commit": {
      "workflow_id": "work_456",
      "timestamp": "2025-06-02T12:00:00Z",
      "transaction": "0x789...",
      "block_number": 12345678,
      "merkle_root": "0xabc..."
    },
    "strategies": [
      {
        "strategy": {
          "name": "token-weighted-voting",
          "version": "1.0.0",
          "hash": "0x1234..."
        },
        "weight": 1.0,
        "parameters": {
          "start_block": 0,
          "end_block": 12345678,
          "min_balance": 100
        }
      }
    ]
  },
  "meta": {
    "timestamp": "2025-06-01T12:00:00Z",
    "request_id": "uuid",
    "version": "1.0"
  }
}

Workflow Status

Workflow status and details are provided by Temporal. The API endpoints that interact with workflows will return Temporal's workflow status and execution details. For more information about Temporal's workflow status and response format, refer to the Temporal documentation.

Error Response Format

{
  "error": {
    "code": "SNAPSHOT_NOT_FOUND",
    "message": "Snapshot with ID snap_123 does not exist",
    "details": {
      "snapshot_id": "snap_123",
      "available_ids": ["snap_124", "snap_125"]
    }
  },
  "meta": {
    "timestamp": "2025-06-01T12:00:00Z",
    "request_id": "uuid",
    "version": "1.0"
  }
}

4. HTTP Status Codes

Success (2xx)

• 200 - Successful GET/PUT/PATCH
• 201 - Successful POST
• 202 - Snapshot execution started (async)
• 204 - Successful DELETE

Client Error (4xx)

• 400 - Bad Request (malformed syntax)
• 401 - Unauthorized (missing/invalid token)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource Not Found
• 409 - Workflow already running for snapshot
• 422 - Validation Error
• 429 - Too Many Requests

Server Error (5xx)

• 500 - Internal Server Error
• 502 - Bad Gateway
• 503 - Service Unavailable
• 504 - Gateway Timeout

5. Rate Limiting

Limits

• Snapshot operations: 10/hour per staff member
• Data queries: 1000/hour per staff member
• Status checks: No limit

Headers

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1625097600
X-RateLimit-Resource: snapshots

6. CORS Policy

Access-Control-Allow-Origin: https://{HOST}
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Request-ID
Access-Control-Max-Age: 86400

Note: After generating a consent link for a snapshot, strategies are locked. Changing strategies after this point invalidates previous consents and requires a new consent link and new round of consent collection.