DOE Hardware Asset Management POC - Mock APIs

A comprehensive mock API system for the Department of Education's Hardware Asset Management proof of concept, providing realistic Microsoft Intune and DeviceHub API endpoints with data derived from Advanced Shipment Notice (ASN) imports.

🚀 Overview

This project provides production-ready mock APIs for:

Microsoft Intune API - Full Microsoft Graph API compatible endpoints for device management
DeviceHub API - Enhanced asset management system with comprehensive specifications

The system automatically loads real-world device data from the NYC Chromebook ASN CSV file to provide realistic responses for testing and development.

📋 Table of Contents

Quick Start
API Documentation
- Microsoft Intune API
- DeviceHub API
Data Sources
Features
Installation
Configuration
Usage Examples
Development

🏃 Quick Start

# Clone the repository
git clone <repository-url>
cd doe_mock_apis

# Install dependencies
npm install

# Place your ASN CSV file in the root directory as 'NYC_Chromebook_ASN_Import_350K.csv'

# Start the server
npm start

# Server will be running at http://localhost:3200

📖 API Documentation

Microsoft Intune API (`/api/intune`)

Microsoft Graph API compatible endpoints for Intune device management.

Device Management Endpoints

Base URL: http://localhost:3200/api/intune

List Managed Devices

GET /deviceManagement/managedDevices

Query Parameters:

$skip - Number of records to skip (pagination)
$top - Number of records to return (max 1000)
$filter - Filter expression
$select - Comma-separated list of fields to return
$orderby - Field to order by (append ' desc' for descending)
$count - Set to 'true' to include count in response

Example:

curl "http://localhost:3200/api/intune/deviceManagement/managedDevices?$top=10&$select=deviceName,serialNumber,operatingSystem&$count=true"

Response:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#deviceManagement/managedDevices",
  "@odata.count": 120,
  "value": [
    {
      "id": "uuid-here",
      "deviceName": "NYC-AT61131",
      "serialNumber": "NYC-SN61131",
      "operatingSystem": "ChromeOS",
      "manufacturer": "Google",
      "model": "CC6PF NRD5N",
      "complianceState": "compliant",
      "managementState": "managed",
      "enrolledDateTime": "2024-01-15T10:30:00Z",
      "lastSyncDateTime": "2024-09-09T08:15:00Z"
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$skip=10&$top=10"
}

Get Specific Device

GET /deviceManagement/managedDevices/{id}

Device Actions

POST /deviceManagement/managedDevices/{id}/retire
POST /deviceManagement/managedDevices/{id}/wipe
POST /deviceManagement/managedDevices/{id}/syncDevice

Windows Protection State

GET /deviceManagement/managedDevices/{id}/windowsProtectionState

Export Jobs (Reports)

GET /deviceManagement/reports/exportJobs

Device Properties

Each managed device includes comprehensive properties:

Basic Info: deviceName, serialNumber, manufacturer, model, operatingSystem
Management: managementState, complianceState, enrolledDateTime, lastSyncDateTime
User Info: userPrincipalName, emailAddress, userDisplayName
Hardware: physicalMemoryInBytes, totalStorageSpaceInBytes, processorArchitecture
Network: wiFiMacAddress, ethernetMacAddress
ChromeOS Specific: chromeOSDeviceInfo with annotatedAssetId, supportEndDateTime
Security: isEncrypted, jailBroken, partnerReportedThreatState

DeviceHub API (`/api/devicehub`)

Enhanced asset management system with comprehensive device specifications and lifecycle management.

Asset Management Endpoints

Base URL: http://localhost:3200/api/devicehub

List Assets

GET /assets

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 50)
status - Filter by status (Active, In Transit, Repair, etc.)
category - Filter by category (Chromebook, Laptop, Desktop, etc.)
department - Filter by department
building - Filter by building
manufacturer - Filter by manufacturer
assignee - Filter by assignee name/email
serialNumber - Filter by serial number
assetTag - Filter by asset tag
search - Global search across multiple fields

Example:

curl "http://localhost:3200/api/devicehub/assets?category=chromebook&status=active&page=1&limit=10"

Response:

{
  "data": [
    {
      "assetId": "DH-NYC-AT61131",
      "deviceId": "uuid-here",
      "assetTag": "NYC-AT61131",
      "serialNumber": "NYC-SN61131",
      "manufacturer": "Google",
      "model": "CC6PF NRD5N",
      "category": "Chromebook",
      "subCategory": "Student Device",
      "status": "Active",
      "condition": "Good",
      "location": {
        "building": "PS 123",
        "floor": "Floor 2",
        "room": "Room 205",
        "department": "Mathematics",
        "zone": "Zone-C",
        "coordinates": {
          "latitude": 40.7128,
          "longitude": -74.0060
        }
      },
      "assignedTo": {
        "employeeId": "STU-000001",
        "name": "Alex Johnson",
        "email": "student1@nycdoe.edu",
        "department": "Mathematics",
        "title": "Student",
        "grade": "Grade 7",
        "studentId": "NYC00000001",
        "schoolYear": "2024-2025"
      },
      "specifications": {
        "processor": "MediaTek Kompanio 520",
        "memory": "4GB LPDDR4",
        "storage": "64GB eMMC",
        "display": "11.6\" HD",
        "operatingSystem": "ChromeOS",
        "osVersion": "ChromeOS 118.0.5993.89",
        "batteryLife": "10 hours",
        "weight": "3.2 lbs",
        "networkInterfaces": [
          {
            "type": "WiFi",
            "macAddress": "00:1A:2B:3C:4D:5E",
            "standard": "802.11ac",
            "speed": "867 Mbps"
          }
        ]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15,
    "hasNext": true,
    "hasPrev": false
  },
  "summary": {
    "totalAssets": 150,
    "categories": ["Chromebook", "Laptop", "Desktop", "Tablet"],
    "manufacturers": ["Google", "Apple", "Dell", "HP"],
    "statuses": ["Active", "In Transit", "Repair"]
  }
}

Get Asset by ID

GET /assets/{assetId}

Get Asset by Serial Number

GET /assets/serial/{serialNumber}

Get Asset by Asset Tag

GET /assets/tag/{assetTag}

Audit Asset

POST /assets/{assetId}/audit

Assign Asset

PUT /assets/{assetId}/assign

Request Body:

{
  "employeeId": "STU-000123",
  "name": "Student Name",
  "email": "student@nycdoe.edu",
  "department": "Mathematics",
  "title": "Student"
}

Reporting Endpoints

Summary Report

GET /reports/summary

Returns comprehensive statistics including:

Asset counts by category, status, manufacturer, location
Compliance overview
Financial summary (total value, depreciation)
Maintenance alerts

Usage Analytics

GET /analytics/usage

Returns usage analytics including:

Device utilization levels (high/medium/low)
Top applications usage
Productivity trends

Asset Properties

Each asset includes detailed information:

Basic Info: assetId, assetTag, serialNumber, manufacturer, model, category
Location: building, floor, room, department, coordinates
Assignment: employee details, grade level, school year
Purchase Info: purchase date/price, vendor, PO number, warranty
Shipping Info: ship date, carrier, tracking number, received date
Specifications: processor, memory, storage, display, network interfaces
Compliance: audit dates, security patches, policies applied
Lifecycle: deployment date, refresh date, depreciation
Maintenance: maintenance history, support contacts
Usage Analytics: daily usage, login counts, application usage
Integration IDs: links to other systems (Intune, inventory systems)

📊 Data Sources

ASN (Advanced Shipment Notice) Integration

The system automatically loads device data from the ASN CSV file (NYC_Chromebook_ASN_Import_350K.csv) with the following fields:

Account name, PO number, Purchase order number
Vendor, Manufacturer, Model id
Serial, Asset tag, Quantity
Ship date, Carrier, Tracking number
Ship to address (street, city, state, zip)
Order date, SVC contract end date

This real-world data ensures realistic testing scenarios and authentic device information.

Generated Data

Additional synthetic data is generated for:

Device specifications and technical details
User assignments and educational programs
Usage analytics and productivity metrics
Compliance and security information
Maintenance history and lifecycle data

✨ Features

Microsoft Intune API

✅ Full Microsoft Graph API compatibility
✅ OData query support ($filter, $select, $orderby, etc.)
✅ Pagination with $skip and $top
✅ Device management actions (retire, wipe, sync)
✅ Windows protection state monitoring
✅ ChromeOS device information
✅ Realistic device properties based on ASN data
✅ Export jobs for reporting

DeviceHub API

✅ Comprehensive asset management
✅ Advanced filtering and search
✅ Detailed device specifications
✅ Location and assignment tracking
✅ Financial and lifecycle management
✅ Compliance and security monitoring
✅ Usage analytics and reporting
✅ Maintenance history tracking
✅ Multi-system integration IDs

Data Features

✅ ASN CSV integration for realistic device data
✅ Educational context (student assignments, grade levels)
✅ NYC DOE specific information
✅ Comprehensive device specifications
✅ Lifecycle and depreciation tracking
✅ Usage analytics and productivity metrics

🛠️ Installation

Prerequisites

Node.js 16+
npm or yarn

Steps

Clone the repository

git clone <repository-url>
cd doe_mock_apis

Install dependencies

npm install

Add ASN CSV file Place your ASN CSV file in the root directory with the name NYC_Chromebook_ASN_Import_350K.csv
Start the server

# Development mode (with auto-restart)
npm run dev

# Production mode
npm start

Verify installation Navigate to http://localhost:3200 to see the API documentation page.

Docker Deployment

For containerized deployment (recommended for production):

Build the Docker image

docker build -t doe-mock-apis .

Run the container

docker run -p 3200:3200 doe-mock-apis

Or use Docker Compose

docker-compose up -d

Sliplane.io Deployment

This project is optimized for Sliplane.io deployment:

Connect your repository to Sliplane
Set environment variables (optional):
- PORT=3200 (default)
- NODE_ENV=production
Deploy - Sliplane will automatically detect the Dockerfile
Access your API at your assigned Sliplane URL

The Docker image includes:

✅ Optimized Node.js 18 Alpine base
✅ Non-root user for security
✅ Health checks for monitoring
✅ Production-ready configuration
✅ Automatic CSV data loading

⚙️ Configuration

Environment Variables

PORT - Server port (default: 3200)

CSV File Configuration

The system expects a CSV file with the following columns:

Account name
PO number
Purchase order number
Vendor
Manufacturer
Model id
Serial
Asset tag
Quantity
Ship date
Carrier
Tracking number
Ship to address street
Ship to address city
Ship to address state
Ship to address zip
Order date
SVC contract end date

💡 Usage Examples

Intune API Examples

Get all devices with pagination:

curl "http://localhost:3200/api/intune/deviceManagement/managedDevices?$top=5&$skip=0"

Filter Chromebooks only:

curl "http://localhost:3200/api/intune/deviceManagement/managedDevices?$filter=chromeOS"

Get specific device fields:

curl "http://localhost:3200/api/intune/deviceManagement/managedDevices?$select=deviceName,serialNumber,complianceState&$top=10"

Sync a device:

curl -X POST "http://localhost:3200/api/intune/deviceManagement/managedDevices/{deviceId}/syncDevice"

DeviceHub API Examples

Get all Chromebooks:

curl "http://localhost:3200/api/devicehub/assets?category=chromebook"

Search for assets:

curl "http://localhost:3200/api/devicehub/assets?search=NYC-AT61131"

Get assets by building:

curl "http://localhost:3200/api/devicehub/assets?building=PS%20123"

Assign asset to student:

curl -X PUT "http://localhost:3200/api/devicehub/assets/DH-NYC-AT61131/assign" \
  -H "Content-Type: application/json" \
  -d '{"employeeId": "STU-999999", "name": "New Student", "email": "newstudent@nycdoe.edu", "department": "Science", "title": "Student"}'

Generate summary report:

curl "http://localhost:3200/api/devicehub/reports/summary"

🏗️ Development

Project Structure

doe_mock_apis/
├── src/
│   ├── server.js           # Main server file
│   └── routes/
│       ├── intune.js       # Microsoft Intune API routes
│       └── devicehub.js    # DeviceHub API routes
├── package.json
├── README.md
└── NYC_Chromebook_ASN_Import_350K.csv  # ASN data file

Adding New Features

Intune API Extensions: Modify src/routes/intune.js
DeviceHub API Extensions: Modify src/routes/devicehub.js
Data Models: Update the data generation functions in respective route files

Testing

# Install development dependencies
npm install --dev

# Run tests
npm test

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

This project is licensed under the ISC License - see the package.json file for details.

🤝 Support

For questions or support, please contact the development team or create an issue in the repository.

📝 Changelog

Version 2.0.0

BREAKING: Removed ServiceNow identification/reconciliation engine
NEW: Full Microsoft Graph API compatibility for Intune endpoints
NEW: Enhanced DeviceHub API with comprehensive asset specifications
NEW: ASN CSV integration for realistic device data
NEW: Educational context (student assignments, grade levels)
IMPROVED: Comprehensive API documentation
IMPROVED: Enhanced filtering and search capabilities
IMPROVED: Detailed device specifications and lifecycle management

Version 1.0.0

Initial release with basic mock APIs

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.claude		.claude
scripts		scripts
servicenow		servicenow
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
DEPLOYMENT-SQLITE.md		DEPLOYMENT-SQLITE.md
Dockerfile		Dockerfile
Dockerfile.multistage		Dockerfile.multistage
Dockerfile.sqlite		Dockerfile.sqlite
NYC_Chromebook_ASN_Import_350K.csv		NYC_Chromebook_ASN_Import_350K.csv
README-SQLITE.md		README-SQLITE.md
README.md		README.md
api_server.py		api_server.py
architecture-diagram.md		architecture-diagram.md
create_database.py		create_database.py
docker-compose.sqlite.yml		docker-compose.sqlite.yml
docker-compose.yml		docker-compose.yml
executive-summary.html		executive-summary.html
openapi.yaml		openapi.yaml
package-lock.json		package-lock.json
package.json		package.json

michaelbuckner/HAMMockApis

Folders and files

Latest commit

History

Repository files navigation