API Integration

Overview

This document provides detailed integration of n8n with various API services in the Sysadmin Anywhere ecosystem, including request examples, data formats, and best practices.

API Integration Architecture

Services and Endpoints

Service	Port	Base URL	Main Endpoints
Main Service	8080	http://sysadminanywhere:8080	/api/*, /actuator/*
Directory Service	8081	http://directory:8080	/api/users/*, /api/groups/*
Inventory Service	8082	http://inventory:8080	/api/computers/*, /api/software/*
Incident Service	8083	http://incident:8080	/api/incidents/*, /api/events/*

Authentication

All services use JWT tokens for authentication. In n8n, configure HTTP Basic Auth credentials using API keys.

Directory Service API

User Management

Get User List

{
  "method": "GET",
  "url": "http://directory:8080/api/users",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "page": 0,
    "size": 50,
    "filter": "active"
  }
}

Create User

{
  "method": "POST",
  "url": "http://directory:8080/api/users",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "username": "{{ $json.username }}",
    "firstName": "{{ $json.firstName }}",
    "lastName": "{{ $json.lastName }}",
    "email": "{{ $json.email }}",
    "department": "{{ $json.department }}",
    "title": "{{ $json.title }}",
    "password": "{{ $json.tempPassword }}",
    "groups": "{{ $json.groups || [] }}"
  }
}

Update User

{
  "method": "PUT",
  "url": "http://directory:8080/api/users/{{ $json.username }}",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "firstName": "{{ $json.firstName }}",
    "lastName": "{{ $json.lastName }}",
    "email": "{{ $json.email }}",
    "department": "{{ $json.department }}",
    "title": "{{ $json.title }}"
  }
}

Lock User Account

{
  "method": "POST",
  "url": "http://directory:8080/api/users/{{ $json.username }}/disable",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "reason": "{{ $json.reason }}",
    "disabledBy": "automation"
  }
}

Reset Password

{
  "method": "POST",
  "url": "http://directory:8080/api/users/{{ $json.username }}/reset-password",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "newPassword": "{{ $json.newPassword }}",
    "forceChangeOnNextLogin": true,
    "reason": "{{ $json.reason }}"
  }
}

Group Management

Get User Groups

{
  "method": "GET",
  "url": "http://directory:8080/api/users/{{ $json.username }}/groups",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  }
}

Add User to Groups

{
  "method": "POST",
  "url": "http://directory:8080/api/users/{{ $json.username }}/groups",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "groups": "{{ $json.groups }}"
  }
}

Search and Filtering

Search Users

{
  "method": "GET",
  "url": "http://directory:8080/api/users/search",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "query": "{{ $json.searchQuery }}",
    "department": "{{ $json.department }}",
    "active": "{{ $json.active || true }}"
  }
}

Get Inactive Users

{
  "method": "GET",
  "url": "http://directory:8080/api/users/inactive",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "days": "{{ $json.days || 90 }}"
  }
}

Inventory Service API

Computer Management

Get Computer List

{
  "method": "GET",
  "url": "http://inventory:8080/api/computers",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "page": 0,
    "size": 50,
    "status": "{{ $json.status || 'all' }}"
  }
}

Get Computer Information

{
  "method": "GET",
  "url": "http://inventory:8080/api/computers/{{ $json.computerName }}",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  }
}

Start Computer Scan

{
  "method": "POST",
  "url": "http://inventory:8080/api/computers/{{ $json.computerName }}/scan",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "scanType": "{{ $json.scanType || 'full' }}",
    "priority": "{{ $json.priority || 'normal' }}"
  }
}

Software Management

Get Installed Software

{
  "method": "GET",
  "url": "http://inventory:8080/api/computers/{{ $json.computerName }}/software",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "includeVersion": "{{ $json.includeVersion || true }}"
  }
}

Search Software by Name

{
  "method": "GET",
  "url": "http://inventory:8080/api/software/search",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "name": "{{ $json.softwareName }}",
    "version": "{{ $json.version }}",
    "computer": "{{ $json.computerName }}"
  }
}

Performance Metrics

Get Computer Metrics

{
  "method": "GET",
  "url": "http://inventory:8080/api/computers/{{ $json.computerName }}/metrics",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "period": "{{ $json.period || '1h' }}",
    "metric": "{{ $json.metric || 'all' }}"
  }
}

Get Disk Usage

{
  "method": "GET",
  "url": "http://inventory:8080/api/computers/{{ $json.computerName }}/disk-usage",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  }
}

Incident Service API

Incident Management

Create Incident

{
  "method": "POST",
  "url": "http://incident:8080/api/incidents",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "title": "{{ $json.title }}",
    "description": "{{ $json.description }}",
    "severity": "{{ $json.severity || 'medium' }}",
    "assignedTo": "{{ $json.assignedTo }}",
    "category": "{{ $json.category }}",
    "source": "automation",
    "tags": "{{ $json.tags || [] }}"
  }
}

Get Incidents

{
  "method": "GET",
  "url": "http://incident:8080/api/incidents",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "status": "{{ $json.status || 'open' }}",
    "severity": "{{ $json.severity }}",
    "assignedTo": "{{ $json.assignedTo }}",
    "page": 0,
    "size": 50
  }
}

Update Incident

{
  "method": "PUT",
  "url": "http://incident:8080/api/incidents/{{ $json.incidentId }}",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "status": "{{ $json.status }}",
    "description": "{{ $json.description }}",
    "assignedTo": "{{ $json.assignedTo }}",
    "resolution": "{{ $json.resolution }}"
  }
}

Event Management

Get Security Events

{
  "method": "GET",
  "url": "http://incident:8080/api/events",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "eventType": "{{ $json.eventType }}",
    "severity": "{{ $json.severity }}",
    "startDate": "{{ $json.startDate }}",
    "endDate": "{{ $json.endDate }}",
    "page": 0,
    "size": 100
  }
}

Create Event

{
  "method": "POST",
  "url": "http://incident:8080/api/events",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "eventType": "{{ $json.eventType }}",
    "severity": "{{ $json.severity }}",
    "description": "{{ $json.description }}",
    "source": "{{ $json.source }}",
    "username": "{{ $json.username }}",
    "computerName": "{{ $json.computerName }}",
    "details": "{{ $json.details || {} }}",
    "timestamp": "{{ $json.timestamp || new Date().toISOString() }}"
  }
}

Audit Log

Write to Audit Log

{
  "method": "POST",
  "url": "http://incident:8080/api/audit-log",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "action": "{{ $json.action }}",
    "username": "{{ $json.username }}",
    "actionType": "{{ $json.actionType }}",
    "reason": "{{ $json.reason }}",
    "details": "{{ $json.details || {} }}",
    "timestamp": "{{ $json.timestamp || new Date().toISOString() }}",
    "source": "automation"
  }
}

Main Service API

System Metrics

Get Performance Metrics

{
  "method": "GET",
  "url": "http://sysadminanywhere:8080/api/metrics/system",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  },
  "qs": {
    "period": "{{ $json.period || '1h' }}"
  }
}

Health Check All Services

{
  "method": "GET",
  "url": "http://sysadminanywhere:8080/api/health/all",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  }
}

Report Management

Generate Report

{
  "method": "POST",
  "url": "http://sysadminanywhere:8080/api/reports/generate",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}",
    "Content-Type": "application/json"
  },
  "body": {
    "reportType": "{{ $json.reportType }}",
    "parameters": "{{ $json.parameters || {} }}",
    "format": "{{ $json.format || 'pdf' }}",
    "recipients": "{{ $json.recipients || [] }}"
  }
}

Get Report Status

{
  "method": "GET",
  "url": "http://sysadminanywhere:8080/api/reports/{{ $json.reportId }}/status",
  "headers": {
    "Authorization": "Bearer {{ $credentials.jwtToken }}"
  }
}

Complex Workflow Examples

Workflow 1: Automated New Employee Processing

{
  "name": "New Employee Onboarding",
  "nodes": [
    {
      "name": "HR System Webhook",
      "type": "n8n-nodes-base.webhook",
      "parameters": {
        "path": "new-employee",
        "method": "POST"
      }
    },
    {
      "name": "Create AD User",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://directory:8080/api/users",
        "method": "POST",
        "body": {
          "username": "={{ $json.firstName.toLowerCase() + '.' + $json.lastName.toLowerCase() }}",
          "firstName": "={{ $json.firstName }}",
          "lastName": "={{ $json.lastName }}",
          "email": "={{ $json.email }}",
          "department": "={{ $json.department }}",
          "title": "={{ $json.title }}",
          "password": "={{ $json.tempPassword }}",
          "groups": ["Domain Users", "{{ $json.department }} Users"]
        }
      }
    },
    {
      "name": "Assign Computer",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://inventory:8080/api/computers/assign",
        "method": "POST",
        "body": {
          "computerName": "={{ $json.computerName }}",
          "username": "={{ $json.firstName.toLowerCase() + '.' + $json.lastName.toLowerCase() }}",
          "department": "={{ $json.department }}"
        }
      }
    },
    {
      "name": "Create Welcome Ticket",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://incident:8080/api/incidents",
        "method": "POST",
        "body": {
          "title": "New Employee Setup: {{ $json.firstName }} {{ $json.lastName }}",
          "description": "Please complete the following tasks for new employee:\\n\\n1. Account created: {{ $json.firstName.toLowerCase() + '.' + $json.lastName.toLowerCase() }}\\n2. Computer assigned: {{ $json.computerName }}\\n3. Department: {{ $json.department }}\\n\\nPlease verify all access and setup.",
          "assignedTo": "it-support",
          "category": "onboarding",
          "severity": "medium"
        }
      }
    },
    {
      "name": "Send Welcome Email",
      "type": "n8n-nodes-base.emailSend",
      "parameters": {
        "toEmail": "={{ $json.email }}",
        "subject": "Welcome to the Company!",
        "text": "Dear {{ $json.firstName }},\\n\\nWelcome to our company! Your account has been created with the following details:\\n\\nUsername: {{ $json.firstName.toLowerCase() + '.' + $json.lastName.toLowerCase() }}\\nTemporary Password: {{ $json.tempPassword }}\\nComputer: {{ $json.computerName }}\\n\\nPlease change your password on first login.\\n\\nBest regards,\\nIT Department"
      }
    }
  ]
}

Workflow 2: Monitoring and Automatic Recovery

{
  "name": "Service Recovery Automation",
  "nodes": [
    {
      "name": "Health Check Trigger",
      "type": "n8n-nodes-base.cron",
      "parameters": {
        "cronExpression": "*/2 * * * *"
      }
    },
    {
      "name": "Check All Services",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://sysadminanywhere:8080/api/health/all",
        "method": "GET"
      }
    },
    {
      "name": "Filter Unhealthy Services",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "functionCode": "const services = $json.services || [];\nconst unhealthy = services.filter(s => s.status !== 'UP');\nreturn unhealthy.map(service => ({ json: service }));"
      }
    },
    {
      "name": "Attempt Restart",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://sysadminanywhere:8080/api/services/{{ $json.name }}/restart",
        "method": "POST"
      }
    },
    {
      "name": "Wait for Recovery",
      "type": "n8n-nodes-base.wait",
      "parameters": {
        "amount": 30,
        "unit": "seconds"
      }
    },
    {
      "name": "Verify Recovery",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://{{ $json.name }}:8080/actuator/health",
        "method": "GET"
      }
    },
    {
      "name": "Create Incident if Failed",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://incident:8080/api/incidents",
        "method": "POST",
        "body": {
          "title": "Service Recovery Failed: {{ $json.name }}",
          "description": "Automatic restart of {{ $json.name }} failed. Manual intervention required.",
          "severity": "critical",
          "assignedTo": "ops-team"
        }
      }
    }
  ]
}

Error Handling and Retry Logic

Retry Configuration

{
  "retryOnFail": true,
  "maxTries": 3,
  "waitBetween": 5000,
  "continueOnFail": false
}

Error Handling Workflow

{
  "name": "Error Handler",
  "nodes": [
    {
      "name": "Error Trigger",
      "type": "n8n-nodes-base.errorTrigger",
      "parameters": {
        "includeWorkflowIds": ["workflow-id-1", "workflow-id-2"]
      }
    },
    {
      "name": "Log Error",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "http://incident:8080/api/errors",
        "method": "POST",
        "body": {
          "workflowId": "{{ $json.workflowId }}",
          "errorMessage": "{{ $json.errorMessage }}",
          "executionId": "{{ $json.executionId }}",
          "timestamp": "{{ new Date().toISOString() }}"
        }
      }
    },
    {
      "name": "Send Alert",
      "type": "n8n-nodes-base.emailSend",
      "parameters": {
        "toEmail": "[email protected]",
        "subject": "Workflow Error: {{ $json.workflowId }}",
        "text": "Workflow execution failed:\\n\\nWorkflow: {{ $json.workflowId }}\\nExecution: {{ $json.executionId }}\\nError: {{ $json.errorMessage }}\\nTime: {{ new Date().toISOString() }}"
      }
    }
  ]
}

Best Practices

1. Security

• Use credentials for storing API keys
• Apply minimal access permissions
• Update tokens regularly
• Log all API calls

2. Performance

• Use pagination for large data volumes
• Cache rarely changing data
• Optimize API requests
• Monitor execution time

3. Reliability

• Implement retry mechanisms
• Handle errors gracefully
• Use circuit breakers
• Create backup workflows

4. Monitoring

• Log all executions
• Track performance metrics
• Set up error alerts
• Regularly check functionality

API Integration Testing

Unit Tests

// Test user creation
const testCreateUser = async () => {
  const userData = {
    username: "test.user",
    firstName: "Test",
    lastName: "User",
    email: "[email protected]"
  };

  const response = await makeApiCall('POST', '/api/users', userData);
  expect(response.status).toBe(201);
  expect(response.data.username).toBe(userData.username);
};

Integration Tests

// Test complete workflow
const testOnboardingWorkflow = async () => {
  // 1. Create user
  const user = await createUser(testUserData);

  // 2. Assign computer
  const computer = await assignComputer(user.username, testComputerData);

  // 3. Create incident
  const incident = await createIncident({
    title: `Onboarding: ${user.username}`,
    assignedTo: "it-support"
  });

  expect(incident.status).toBe('open');
};

Conclusion

Proper integration of n8n with Sysadmin Anywhere API services enables powerful automated solutions for IT infrastructure management. Follow these guidelines to create reliable and efficient workflows.