CepatEdge

Appearance

API Documentation ​

This directory contains comprehensive API documentation for CepatEdge.

API Overview ​

CepatEdge provides RESTful APIs for maintenance management with the following characteristics:

  • Base URL: https://api.cepatedge.com (local: http://localhost:8787)
  • Authentication: JWT Bearer tokens
  • Format: JSON
  • Versioning: URL-based versioning (/api/v1/)
  • Rate Limiting: 1000 requests per hour per user

Authentication ​

All API endpoints require authentication except for authentication endpoints themselves.

Obtaining Access Tokens ​

bash
POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "password"
}

Response:

json
{
  "code": "OK",
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
      "user": {
      "id": 1,
      "email": "[email protected]",
      "role": "employee"
      }
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Using Access Tokens ​

Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Core API Endpoints ​

Maintenance Management ​

  • GET /maintenance - List maintenance requests
  • POST /maintenance - Create new request
  • GET /maintenance/:id - Get specific request
  • PUT /maintenance/:id - Update request (content fields; employee submitter pre-approval only)
  • DELETE /maintenance/:id - Cancel request (body: reason, optional attachmentIds)
  • DELETE /maintenance/:id/delete - Permanently delete a cancelled request and attachments (maintenance.purge_cancelled; JSON body: { "reason": "…" } required)

Workflow Operations ​

  • PUT /maintenance/:id/approve - Approve request (department head)
  • PUT /maintenance/:id/assign - Assign technician
  • PUT /maintenance/:id/complete - Mark as completed

Maintenance Attachments (R2) ​

  • GET /maintenance/:requestId/attachments - List attachments
  • POST /maintenance/:requestId/attachments - Upload (multipart: type BEFORE|AFTER, file)
  • GET /maintenance/attachments/:attachmentId - Stream file
  • DELETE /maintenance/attachments/:attachmentId - Delete attachment

User Management ​

  • GET /api/users - List users (admin only)
  • GET /api/users/:id - Get user details
  • PUT /api/users/:id - Update user

Avatar (R2) ​

  • GET /me/avatar - Get current user avatar metadata (includes id, use it to load image)
  • GET /me/avatar/:id - Stream avatar image file by avatar id (path from user cache)
  • POST /me/avatar/upload - Upload avatar (multipart: file, optional filename)
  • DELETE /me/avatar - Delete avatar

System Endpoints ​

  • GET /api/health - Health check
  • GET /api/system/info - System information

Error Handling ​

All errors follow a consistent format:

json
{
  "code": "VALIDATION_ERROR",
  "success": false,
  "error": {
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

OpenAPI Specification ​

Complete API specification available at /docs/openapi.json endpoint in JSON format, compatible with:

  • Postman
  • Insomnia
  • Yaak

Interactive API documentation available at /docs endpoint with Swagger UI.

Rate Limiting ​

  • Authenticated Users: 1000 requests/hour
  • Unauthenticated: 100 requests/hour
  • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Webhooks ​

CepatEdge supports webhooks for real-time notifications:

json
{
  "event": "maintenance.status_changed",
  "data": {
    "id": 123,
    "status": "approved",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

SDKs and Libraries ​

  • JavaScript/TypeScript: Official SDK available
  • Python: Community-maintained library
  • Go: Community-maintained library

Support ​

For API support:

  • Check the OpenAPI specification first
  • Review error messages for guidance
  • Contact support for complex integration issues