Work and Asset Management API

A comprehensive REST API for managing work orders, assets, maintenance schedules, and facility management operations.

Overview

The Work and Asset Management API provides a robust backend solution for organizations to track, manage, and maintain their physical assets and work operations. This API enables efficient management of work orders, asset lifecycle, preventive maintenance, and resource allocation.

Features

Core Functionality

• Work Order Management

  • Create, update, and track work orders
  • Assign technicians and resources
  • Priority-based scheduling
  • Status tracking and updates
  • Work order history and analytics

• Asset Management

  • Complete asset registry and lifecycle tracking
  • Asset categorization and tagging
  • Maintenance history
  • Depreciation tracking
  • Asset performance metrics

• Preventive Maintenance

  • Scheduled maintenance plans
  • Automated work order generation
  • Maintenance calendar
  • Service interval tracking
  • Compliance management

• Resource Management

  • Technician scheduling and availability
  • Inventory tracking
  • Tool and equipment allocation
  • Cost tracking and budgeting

API Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Client Apps   │────▶│   API Gateway   │────▶│  Work & Asset   │
│  (Web/Mobile)   │     │  (Auth/Routes)  │     │   Management    │
└─────────────────┘     └─────────────────┘     │      API        │
                                                 └─────────────────┘
                                                          │
                                ┌─────────────────────────┴─────────────────────────┐
                                │                                                   │
                        ┌───────▼────────┐  ┌────────▼────────┐  ┌────────▼────────┐
                        │  Work Orders   │  │     Assets      │  │   Maintenance   │
                        │    Service     │  │    Service      │  │    Service      │
                        └────────────────┘  └─────────────────┘  └─────────────────┘
                                │                    │                     │
                        ┌───────▼────────────────────▼─────────────────────▼────────┐
                        │                         Database                           │
                        │  (Work Orders, Assets, Maintenance, Users, Resources)     │
                        └───────────────────────────────────────────────────────────┘

API Endpoints

Authentication

POST   /api/auth/login         # User login
POST   /api/auth/logout        # User logout
POST   /api/auth/refresh       # Refresh access token

Work Orders

GET    /api/work-orders              # List all work orders
POST   /api/work-orders              # Create new work order
GET    /api/work-orders/:id          # Get specific work order
PUT    /api/work-orders/:id          # Update work order
DELETE /api/work-orders/:id          # Delete work order
POST   /api/work-orders/:id/assign   # Assign technician
POST   /api/work-orders/:id/complete # Complete work order

Assets

GET    /api/assets                   # List all assets
POST   /api/assets                   # Create new asset
GET    /api/assets/:id               # Get specific asset
PUT    /api/assets/:id               # Update asset
DELETE /api/assets/:id               # Delete asset
GET    /api/assets/:id/history       # Get asset maintenance history
POST   /api/assets/:id/maintenance   # Schedule maintenance

Maintenance

GET    /api/maintenance/schedules    # List maintenance schedules
POST   /api/maintenance/schedules    # Create maintenance schedule
GET    /api/maintenance/calendar     # Get maintenance calendar
POST   /api/maintenance/preventive   # Create preventive maintenance plan

Resources

GET    /api/technicians              # List technicians
GET    /api/technicians/:id/schedule # Get technician schedule
POST   /api/technicians/:id/assign   # Assign to work order
GET    /api/inventory                # List inventory items
PUT    /api/inventory/:id            # Update inventory levels

Reports

GET    /api/reports/work-orders      # Work order analytics
GET    /api/reports/assets           # Asset performance reports
GET    /api/reports/maintenance      # Maintenance compliance reports
GET    /api/reports/costs            # Cost analysis reports

Data Models

Work Order

{
  "id": "WO-2024-001",
  "title": "Repair HVAC Unit",
  "description": "AC unit not cooling properly",
  "priority": "high",
  "status": "in_progress",
  "assetId": "ASSET-HVAC-001",
  "assignedTo": "TECH-001",
  "createdDate": "2024-03-20T10:00:00Z",
  "dueDate": "2024-03-21T17:00:00Z",
  "completedDate": null,
  "estimatedHours": 4,
  "actualHours": null,
  "cost": {
    "labor": 0,
    "parts": 0,
    "total": 0
  }
}

Asset

{
  "id": "ASSET-HVAC-001",
  "name": "HVAC Unit - Building A",
  "type": "HVAC",
  "category": "Facility",
  "location": {
    "building": "A",
    "floor": "3",
    "room": "301"
  },
  "purchaseDate": "2020-01-15",
  "warrantyExpiration": "2025-01-15",
  "maintenanceSchedule": "quarterly",
  "status": "operational",
  "specifications": {
    "manufacturer": "Carrier",
    "model": "38TRA016",
    "serialNumber": "SN123456789"
  }
}

Maintenance Schedule

{
  "id": "MS-001",
  "assetId": "ASSET-HVAC-001",
  "type": "preventive",
  "frequency": "quarterly",
  "lastPerformed": "2024-01-15",
  "nextDue": "2024-04-15",
  "tasks": [
    "Replace air filters",
    "Check refrigerant levels",
    "Clean coils",
    "Test thermostat"
  ]
}

Installation

Prerequisites

• Node.js 18+ or Python 3.9+
• PostgreSQL 13+ or MongoDB 5+
• Redis (for caching)
• Docker (optional)

Quick Start

1. Clone the repository:

git clone https://github.com/msaleme/Work-and-Asset-Management-API.git
cd Work-and-Asset-Management-API

2. Install dependencies:

npm install
# or
pip install -r requirements.txt

3. Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

4. Initialize the database:

npm run db:migrate
# or
python manage.py migrate

5. Start the server:

npm start
# or
python manage.py runserver

Docker Deployment

docker-compose up -d

Configuration

Environment Variables

# Server Configuration
PORT=3000
NODE_ENV=production

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/work_asset_db

# Authentication
JWT_SECRET=your-secret-key
JWT_EXPIRATION=24h

# Redis Cache
REDIS_URL=redis://localhost:6379

# Email Service
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=notifications@example.com
SMTP_PASSWORD=your-password

# File Storage
STORAGE_TYPE=s3
AWS_BUCKET_NAME=work-asset-files
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

User Roles

• Admin: Full system access
• Manager: Manage work orders, assets, and technicians
• Technician: View assigned work orders, update status
• Viewer: Read-only access to reports

Error Handling

The API returns standard HTTP status codes and error messages:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Work order not found",
    "details": {
      "workOrderId": "WO-2024-999"
    }
  }
}

Status Codes

• 200 OK - Successful request
• 201 Created - Resource created
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Rate Limiting

API requests are limited to:

• 100 requests per minute for authenticated users
• 20 requests per minute for unauthenticated users

Webhooks

Configure webhooks to receive real-time notifications:

{
  "url": "https://your-app.com/webhooks/work-orders",
  "events": ["work_order.created", "work_order.completed"],
  "secret": "your-webhook-secret"
}

Testing

Run the test suite:

npm test
# or
pytest

Run with coverage:

npm run test:coverage
# or
pytest --cov

API Documentation

• Interactive API documentation available at /api/docs
• OpenAPI/Swagger specification at /api/openapi.json
• Postman collection available in /docs/postman_collection.json

Performance Optimization

• Database queries are optimized with proper indexing
• Redis caching for frequently accessed data
• Pagination support for list endpoints
• Bulk operations for batch processing
• Async job processing for heavy operations

Security

• HTTPS only in production
• Input validation and sanitization
• SQL injection protection
• Rate limiting and DDoS protection
• Regular security audits
• OWASP compliance

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Open an issue on GitHub
• Email: support@example.com
• Documentation: https://docs.example.com

Roadmap

• Mobile application support
• IoT sensor integration
• AI-powered predictive maintenance
• Advanced analytics dashboard
• Multi-tenant support
• Offline mode support
• GraphQL API support

Author

Mike Saleme - GitHub