Skip to content

API.md

Latest commit

 

History

History
471 lines (374 loc) · 7.89 KB

API.md

File metadata and controls

471 lines (374 loc) · 7.89 KB

API Reference

Forge REST API documentation for version 1.0.

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

Authentication

Currently, Forge API uses API key authentication (JWT coming soon).

Authorization: Bearer YOUR_API_KEY

Endpoints

Health Check

GET /health

Check API server health and service status.

Response:

{
  "status": "healthy",
  "timestamp": "2024-12-09T12:00:00Z",
  "version": "0.1.0",
  "services": {
    "database": "connected",
    "redis": "connected",
    "weaviate": "connected"
  }
}

Status Codes:

  • 200 - All services healthy
  • 503 - One or more services unavailable

Projects

POST /projects

Create a new project.

Request:

{
  "name": "My Project",
  "description": "Project description",
  "repoUrl": "https://github.com/user/repo"
}

Response:

{
  "id": "proj_abc123",
  "name": "My Project",
  "description": "Project description",
  "repoUrl": "https://github.com/user/repo",
  "createdAt": "2024-12-09T12:00:00Z",
  "updatedAt": "2024-12-09T12:00:00Z"
}

Status Codes:

  • 201 - Project created
  • 400 - Invalid request
  • 409 - Project already exists

GET /projects

List all projects.

Query Parameters:

  • page (optional) - Page number (default: 1)
  • limit (optional) - Items per page (default: 20, max: 100)
  • search (optional) - Search by name

Response:

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "My Project",
      "description": "Project description",
      "specsCount": 5,
      "jobsCount": 12,
      "createdAt": "2024-12-09T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "pages": 3
  }
}

GET /projects/:id

Get a specific project by ID.

Response:

{
  "id": "proj_abc123",
  "name": "My Project",
  "description": "Project description",
  "repoUrl": "https://github.com/user/repo",
  "specs": [
    {
      "id": "spec_xyz789",
      "description": "Add user authentication",
      "status": "completed",
      "createdAt": "2024-12-09T12:00:00Z"
    }
  ],
  "createdAt": "2024-12-09T12:00:00Z",
  "updatedAt": "2024-12-09T12:00:00Z"
}

Status Codes:

  • 200 - Success
  • 404 - Project not found

DELETE /projects/:id

Delete a project.

Status Codes:

  • 204 - Project deleted
  • 404 - Project not found

Specifications

POST /specs

Generate a specification from natural language.

Request:

{
  "projectId": "proj_abc123",
  "description": "Add user authentication with email and password",
  "context": {
    "framework": "express",
    "database": "postgresql"
  }
}

Response:

{
  "id": "spec_xyz789",
  "projectId": "proj_abc123",
  "description": "Add user authentication with email and password",
  "status": "generated",
  "spec": {
    "files": [
      {
        "path": "src/auth/auth.service.ts",
        "action": "create",
        "content": "..."
      },
      {
        "path": "src/users/user.model.ts",
        "action": "modify",
        "changes": [...]
      }
    ],
    "tests": [
      {
        "path": "src/auth/auth.service.test.ts",
        "description": "Test login functionality"
      }
    ],
    "dependencies": [
      "bcrypt",
      "jsonwebtoken",
      "@types/bcrypt"
    ],
    "estimatedComplexity": "medium"
  },
  "createdAt": "2024-12-09T12:00:00Z"
}

Status Codes:

  • 201 - Spec generated
  • 400 - Invalid request
  • 422 - Unable to generate spec

GET /specs/:id

Get a specification by ID.

Response:

{
  "id": "spec_xyz789",
  "projectId": "proj_abc123",
  "description": "Add user authentication",
  "status": "generated",
  "spec": { ... },
  "jobs": [
    {
      "id": "job_123",
      "status": "completed",
      "createdAt": "2024-12-09T12:30:00Z"
    }
  ],
  "createdAt": "2024-12-09T12:00:00Z"
}

Jobs

POST /jobs

Execute a specification.

Request:

{
  "specId": "spec_xyz789",
  "options": {
    "autoApprove": false,
    "createPR": true
  }
}

Response:

{
  "id": "job_123",
  "specId": "spec_xyz789",
  "status": "pending",
  "progress": 0,
  "createdAt": "2024-12-09T12:00:00Z"
}

Status Codes:

  • 201 - Job created
  • 400 - Invalid request
  • 404 - Spec not found

GET /jobs/:id

Get job status and results.

Response:

{
  "id": "job_123",
  "specId": "spec_xyz789",
  "status": "running",
  "progress": 45,
  "logs": [
    "Creating sandbox...",
    "Generating code...",
    "Applying changes..."
  ],
  "result": null,
  "createdAt": "2024-12-09T12:00:00Z",
  "startedAt": "2024-12-09T12:01:00Z",
  "completedAt": null
}

Job Statuses:

  • pending - Waiting to start
  • running - Executing
  • completed - Success
  • failed - Error occurred
  • cancelled - Manually stopped

POST /jobs/:id/cancel

Cancel a running job.

Status Codes:

  • 200 - Job cancelled
  • 400 - Job cannot be cancelled
  • 404 - Job not found

Metrics

GET /metrics

Prometheus-formatted metrics.

Response:

# HELP forge_api_requests_total Total API requests
# TYPE forge_api_requests_total counter
forge_api_requests_total{method="GET",endpoint="/projects",status="200"} 142

# HELP forge_ai_requests_total Total AI provider requests
# TYPE forge_ai_requests_total counter
forge_ai_requests_total{provider="openai",model="gpt-4"} 23

# HELP forge_job_duration_seconds Job execution duration
# TYPE forge_job_duration_seconds histogram
forge_job_duration_seconds_bucket{status="completed",le="10"} 5
forge_job_duration_seconds_bucket{status="completed",le="30"} 12

Error Responses

All errors follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "name",
      "issue": "Required field missing"
    }
  },
  "requestId": "req_xyz123"
}

Common Error Codes:

  • VALIDATION_ERROR - Invalid input
  • NOT_FOUND - Resource not found
  • UNAUTHORIZED - Authentication required
  • FORBIDDEN - Permission denied
  • RATE_LIMIT_EXCEEDED - Too many requests
  • INTERNAL_ERROR - Server error

Rate Limiting

Current limits:

  • 100 requests per minute per IP
  • 1000 requests per hour per API key

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1702134000

Pagination

For list endpoints:

Request:

GET /api/v1/projects?page=2&limit=50

Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 250,
    "pages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

Examples

Complete Workflow

# 1. Create a project
curl -X POST http://localhost:3000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "repoUrl": "https://github.com/user/my-app"
  }'
# Response: { "id": "proj_abc123", ... }

# 2. Generate a spec
curl -X POST http://localhost:3000/api/v1/specs \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "description": "Add user login"
  }'
# Response: { "id": "spec_xyz789", ... }

# 3. Execute the spec
curl -X POST http://localhost:3000/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "specId": "spec_xyz789"
  }'
# Response: { "id": "job_123", "status": "pending" }

# 4. Check job status
curl http://localhost:3000/api/v1/jobs/job_123
# Response: { "id": "job_123", "status": "completed", ... }

Webhooks (Coming Soon)

Subscribe to events:

  • job.completed
  • job.failed
  • spec.generated

OpenAPI / Swagger

Interactive API documentation:

http://localhost:3000/api-docs

OpenAPI spec:

http://localhost:3000/api/v1/openapi.json

Need help? Check the Getting Started Guide or open an issue.

Last Updated: December 9, 2024