API Reference Documentation

Base Configuration

Base URL

Production: https://api.ms-project.com/api/v1
Development: http://localhost:8080/api/v1

Authentication

All API endpoints require JWT Bearer token authentication:

Authorization: Bearer <jwt_token>

Request Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer <jwt_token>

Response Format

{
  "data": {},      // Response payload
  "message": "",   // Success message
  "error": {},     // Error details (if any)
  "meta": {}       // Pagination metadata (if applicable)
}

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Specific field error"
    },
    "statusCode": 400
  }
}

Project Endpoints

List Projects

GET /projects

Retrieves paginated list of projects.

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
limit integer 10 Items per page (max 100)
search string - Search in name/description
sortBy string created_at Sort field
sortOrder string desc Sort direction (asc/desc)
status string - Filter by status
customerId string - Filter by customer
progress string - Filter by progress stage

Response: 200 OK

{
  "data": [
    {
      "id": "01HXYZ123ABC",
      "uniqueCode": "PRJ-2024-001",
      "name": "E-Commerce Platform",
      "status": "approved",
      "progress": "in_production",
      "contractValue": 50000000,
      "currency": "USD",
      "description": "Complete e-commerce solution",
      "replyDate": "2024-12-31T00:00:00Z",
      "customerId": "01HXYZ789DEF",
      "creatorId": "01HXYZ456GHI",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

Get Project

GET /projects/:uniqueCode

Retrieves single project with all relations.

Path Parameters:

  • uniqueCode: Project unique code (e.g., PRJ-2024-001)

Response: 200 OK

{
  "data": {
    "id": "01HXYZ123ABC",
    "uniqueCode": "PRJ-2024-001",
    "name": "E-Commerce Platform",
    "status": "approved",
    "progress": "in_production",
    "contractValue": 50000000,
    "currency": "USD",
    "description": "Complete e-commerce solution",
    "replyDate": "2024-12-31T00:00:00Z",
    "customer": {
      "id": "01HXYZ789DEF",
      "name": "TechCorp Inc.",
      "email": "contact@techcorp.com"
    },
    "creator": {
      "id": "01HXYZ456GHI",
      "name": "John Doe",
      "email": "john@company.com"
    },
    "tasks": [],
    "products": [],
    "participants": []
  }
}

Create Project

POST /projects

Creates a new project.

Request Body:

{
  "name": "New Project",
  "customerId": "01HXYZ789DEF",
  "contractValue": 1000000,
  "currency": "USD",
  "description": "Project description",
  "replyDate": "2024-12-31T00:00:00Z",
  "documentFileIds": ["file1", "file2"],
  "participantIds": ["user1", "user2"],
  "products": [
    {
      "name": "API Management Platform",
      "productType": "software",  // Dynamic types from settings table
      "description": "Cloud-based API gateway",
      "attributes": {
        "name": "API Gateway Pro",
        "version": "2.1.0",
        "licenseType": "subscription",
        "deployment": {
          "type": "saas",
          "platforms": ["web", "docker"]
        },
        "support": {
          "type": "24x7",
          "sla": "99.99%"
        }
      }
    },
    {
      "name": "Implementation Services",
      "productType": "service",  // Dynamic types from settings table
      "description": "Professional implementation support",
      "attributes": {
        "serviceType": "implementation",
        "duration": 30,
        "unit": "days",
        "deliveryMethod": "hybrid",
        "consultantLevel": "senior"
      }
    }
  ]
}

Response: 201 Created

{
  "data": {
    "id": "01HXYZ999ZZZ",
    "uniqueCode": "PRJ-2024-002",
    "name": "New Project",
    // ... full project object
  },
  "message": "Project created successfully"
}

Update Project

PATCH /projects/:uniqueCode

Updates project fields.

Request Body: (all fields optional)

{
  "name": "Updated Name",
  "contractValue": 2000000,
  "description": "Updated description",
  "status": "approved",
  "progress": "in_production"
}

Response: 200 OK

Approve Project

PUT /projects/:uniqueCode/approved

Approves a project (changes status to approved).

Response: 200 OK

{
  "data": {
    "status": "approved",
    // ... full project object
  },
  "message": "Project approved successfully"
}

Update Project Progress

PATCH /projects/:uniqueCode/progress

Updates project progress stage.

Request Body:

{
  "progress": "in_production"
}

Valid Progress Values:

  • technical_negotiating
  • bidding
  • waiting_for_contract
  • contract_negotiating
  • production_planning
  • in_production
  • delivering

Response: 200 OK

Delete Project

DELETE /projects/:uniqueCode

Soft deletes a project.

Response: 204 No Content

Count Project Resources

GET /projects/:uniqueCode/count-resources

Counts related resources for a project.

Query Parameters:

  • resourceTypes[]: Array of resource types to count
    • Valid: Task, PurchaseRequest, PurchaseOrder, Delivery, ProductionOrder

Response: 200 OK

{
  "data": [
    {
      "type": "Task",
      "count": 25,
      "status": "active"
    },
    {
      "type": "PurchaseRequest",
      "count": 5,
      "status": "pending"
    }
  ]
}

Get Project Expenses

GET /projects/:uniqueCode/expenses_count

Gets project expense summary.

Response: 200 OK

{
  "data": {
    "totalExpenses": 15000000,
    "currency": "USD",
    "breakdown": {
      "materials": 8000000,
      "labor": 5000000,
      "overhead": 2000000
    }
  }
}

Product Schema System

Dynamic Product Types

Product types are dynamically loaded from the settings table, not hardcoded in the application.

Available Product Types

The system currently supports:

  • software: Software products with licensing, deployment, and technical specifications
  • service: Service products with delivery methods, pricing, and team composition

Schema Validation

All product attributes are validated against JSON Schema Draft-07 specifications stored in the settings table.

Get Available Product Types

To retrieve available product types, query the settings table:

SELECT value FROM settings WHERE key = 'product_schema_registry';

Registry Format:

{
  "version": "1.0.0",
  "schemas": [
    {
      "type": "software",
      "key": "product_schema:software:v1.0.0",
      "version": "1.0.0",
      "title": "Software Product Schema",
      "active": true,
      "requiredFields": ["name", "version", "licenseType"]
    },
    {
      "type": "service",
      "key": "product_schema:service:v1.0.0",
      "version": "1.0.0",
      "title": "Service Product Schema",
      "active": true,
      "requiredFields": ["serviceType", "duration", "unit"]
    }
  ]
}

Product Validation Errors

When product attributes don't match the schema:

{
  "error": "validation failed for product 'API Gateway': version: Does not match pattern '^\\d+\\.\\d+\\.\\d+