API Reference

Complete API documentation for all endpoints

📋 Overview

This section provides comprehensive API documentation for Izri, covering all tRPC procedures, REST endpoints, and webhook integrations. This reference is essential for frontend developers and API consumers.

🎯 API Architecture

• Primary API: tRPC for type-safe communication
• REST Fallback: Limited REST endpoints for non-TypeScript clients
• Webhooks: GitHub webhook integration for automation

📚 Documentation Pages

tRPC Procedures

Complete tRPC API reference

• All query procedures
• All mutation procedures
• Input/output types
• Error handling
• Usage examples
• Authentication requirements

REST Endpoints

HTTP REST API reference

• Available endpoints
• Request/response formats
• Authentication headers
• Error codes
• Rate limiting
• Examples with curl

Webhooks

Webhook integration guide

• GitHub webhooks
• Event types
• Payload formats
• Signature verification
• Handler implementation
• Testing webhooks

🚀 API Overview

Base URLs

Authentication

// Session-based (current)
// Cookie sent automatically by browser

// API Token (future)
headers: {
  'Authorization': 'Bearer your-api-token'
}

📡 tRPC Procedures

Queries (Read Operations)

Mutations (Write Operations)

📝 Common Types

Project

interface Project {
  id: string
  name: string
  description: string | null
  repository: string
  branch: string
  language: string
  framework: string | null
  userId: string
  organizationId: string | null
  createdAt: Date
  updatedAt: Date
  testRuns?: TestRun[]
}

TestRun

interface TestRun {
  id: string
  projectId: string
  userId: string
  status: TestStatus
  type: TestType
  totalTests: number
  passedTests: number
  failedTests: number
  skippedTests: number
  coverage: number | null
  duration: number | null
  startedAt: Date | null
  completedAt: Date | null
  createdAt: Date
}

enum TestStatus {
  PENDING = 'PENDING',
  RUNNING = 'RUNNING',
  COMPLETED = 'COMPLETED',
  FAILED = 'FAILED',
  CANCELLED = 'CANCELLED'
}

enum TestType {
  UNIT = 'UNIT',
  INTEGRATION = 'INTEGRATION',
  E2E = 'E2E',
  ALL = 'ALL'
}

Repository

interface Repository {
  id: number
  name: string
  fullName: string
  description: string | null
  url: string
  cloneUrl: string
  language: string
  stars: number
  forks: number
  isPrivate: boolean
  updatedAt: string
  defaultBranch: string
}

🔧 Usage Examples

TypeScript/JavaScript (tRPC Client)

import { createTRPCProxyClient, httpBatchLink } from '@trpc/client'
import type { AppRouter } from '@izri/trpc'

const client = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:4000/trpc',
    }),
  ],
})

// Query
const projects = await client.getProjects.query({
  userEmail: 'user@example.com'
})

// Mutation
const newProject = await client.createProject.mutate({
  name: 'My Project',
  description: 'A test project',
  repository: 'https://github.com/user/repo',
  branch: 'main',
  language: 'typescript',
  userEmail: 'user@example.com'
})

React (tRPC Hooks)

import { trpc } from '~/lib/trpc'

function MyComponent() {
  // Query with auto-refetch
  const { data, isLoading, error } = trpc.getProjects.useQuery({
    userEmail: 'user@example.com'
  })

  // Mutation with optimistic updates
  const createProject = trpc.createProject.useMutation({
    onSuccess: () => {
      // Invalidate and refetch
      trpc.useContext().getProjects.invalidate()
    }
  })

  const handleCreate = () => {
    createProject.mutate({
      name: 'New Project',
      repository: 'https://github.com/user/repo',
      branch: 'main',
      language: 'typescript',
      userEmail: 'user@example.com'
    })
  }

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <div>
      {data?.map(project => (
        <div key={project.id}>{project.name}</div>
      ))}
      <button onClick={handleCreate}>Create Project</button>
    </div>
  )
}

curl (REST)

# Health check
curl http://localhost:4000/health

# tRPC query (POST with JSON body)
curl -X POST http://localhost:4000/trpc/getProjects \
  -H "Content-Type: application/json" \
  -d '{"userEmail":"user@example.com"}'

# tRPC mutation
curl -X POST http://localhost:4000/trpc/createProject \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "repository": "https://github.com/user/repo",
    "branch": "main",
    "language": "typescript",
    "userEmail": "user@example.com"
  }'

⚠️ Error Handling

Error Response Format

interface TRPCError {
  message: string
  code: string
  data?: {
    code: string
    httpStatus: number
    path: string
    stack?: string
  }
}

Error Codes

Error Handling Example

try {
  const project = await client.getProject.query({ id: 'invalid-id' })
} catch (error) {
  if (error instanceof TRPCClientError) {
    if (error.data?.code === 'NOT_FOUND') {
      console.log('Project not found')
    } else {
      console.error('API error:', error.message)
    }
  }
}

📊 Rate Limiting

Planned Limits (Not Yet Implemented)

Rate limiting is planned for future implementation to protect against abuse and ensure fair usage.

Future Rate Limit Headers

Once implemented, these headers will be included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
Retry-After: 60

🔐 Authentication

Session Authentication (Current)

// Automatically handled by browser cookies
// No additional headers required

API Token Authentication (Planned)

// In headers
{
  'Authorization': 'Bearer your-api-token'
}

// Example
fetch('http://localhost:4000/trpc/getProjects', {
  headers: {
    'Authorization': 'Bearer sk_live_...'
  }
})

🔗 Related Documentation

• Backend: Backend Documentation
• Frontend: tRPC Integration
• Packages: tRPC Package

📖 Additional Resources

• tRPC Documentation
• Hono Documentation
• Drizzle ORM

Explore detailed API documentation →

• tRPC Procedures Reference
• REST Endpoints Reference
• Webhooks Integration