meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
api [2025/06/07 16:09] – c/e wrongechoapi [2025/06/09 15:26] (current) – added "API Reference Guide" dalton
Line 61: Line 61:
 Documentation / an example of how to use a module API endpoint is shown on that module's doc page. Additional examples are available [[https://github.com/itflow-org/itflow-api-powershell|here]]. Documentation / an example of how to use a module API endpoint is shown on that module's doc page. Additional examples are available [[https://github.com/itflow-org/itflow-api-powershell|here]].
  
 +
 +
 +----
 +
 +
 +====== API Reference Guide ======
 +
 +**Current API v1 Endpoints, Authentication, Examples, and Integration Guide**
 +
 +===== Quick Start Guide =====
 +
 +==== Your First API Call in 5 Minutes ====
 +
 +  - **Generate API Key**
 +    - Login to ITFlow as admin
 +    - Navigate to **Admin > API**
 +    - Click **New Key**
 +    - Choose scope: **All Clients** (for testing) or **Specific Client**
 +    - Copy the generated key
 +
 +  - **Test Connection**
 +<code bash>
 +curl "https://itflow.yourdomain.com/api/v1/clients/read.php?api_key=YOUR_KEY&limit=1"
 +</code>
 +
 +  - **Expected Response**
 +<code json>
 +{
 +  "success": "True",
 +  "count": 1,
 +  "data": [{"client_id": "123", "client_name": "Example Corp"}]
 +}
 +</code>
 +
 +===== API Overview =====
 +
 +**Source**: ITFlow official documentation at docs.itflow.org/api
 +
 +  * **Base URL**: ''/api/v1/{module}/{function}.php''
 +  * **Version**: 1.0 (current)
 +  * **Authentication**: API Key via query parameter ''?api_key=YOUR_KEY''
 +  * **Response Format**: JSON with ''success'', ''message'', ''count'', ''data'' fields
 +  * **Pagination**: Default 50 records, adjustable with ''limit'' and ''offset'' parameters
 +  * **Content-Type**: ''application/json'' for POST requests
 +  * **Character Encoding**: UTF-8 (utf8mb4 in database)
 +
 +==== Standard Response Format ====
 +
 +**Source**: ITFlow official API documentation
 +
 +<code json>
 +{
 +  "success": "True|False",
 +  "message": "Descriptive status message",
 +  "count": 50,
 +  "data": [
 +    {
 +      "id": 123,
 +      "field": "value"
 +    }
 +  ]
 +}
 +</code>
 +
 +===== Authentication & Security =====
 +
 +==== API Key Management ====
 +
 +  * **Generation**: Admin > API > New Key
 +  * **Scoping Options**:
 +    * **All Clients**: Full access to all client data
 +    * **Specific Client**: Limited to single client (''client_id'' required)
 +  * **Usage**: Query parameter ''?api_key=YOUR_KEY''
 +  * **Security**: Keys stored encrypted in database
 +
 +==== Best Practices ====
 +
 +**Source**: MSP community recommendations and security standards
 +
 +  * **Rotate keys** regularly (monthly recommended)
 +  * **Use client-scoped keys** for third-party integrations
 +  * **Store keys securely** (environment variables, not code)
 +  * **Monitor usage** via Apache/PHP logs
 +  * **Use HTTPS only** for all API calls
 +
 +===== Currently Available Modules =====
 +
 +**Source**: ITFlow official API documentation confirms these modules have API support:
 +
 +==== Assets ''/api/v1/assets/'' ====
 +
 +**Purpose**: Computer and equipment inventory management
 +
 +**Source**: [[https://docs.itflow.org/assets|ITFlow Assets Documentation]]
 +
 +  * ''GET /read.php'' - List/get asset information
 +  * ''POST /create.php'' - Create new asset record
 +  * ''POST /update.php'' - Update existing asset
 +  * ''POST /delete.php'' - Delete asset record
 +
 +**Complete Fields** (from ITFlow Assets API Documentation):
 +
 +<code json>
 +{
 +  "asset_id": 123,
 +  "client_id": 456,
 +  "asset_name": "Sample Laptop",
 +  "asset_type": "Laptop",
 +  "asset_make": "Dell",
 +  "asset_model": "Optiplex",
 +  "asset_serial": "XYZ",
 +  "asset_os": "Win 10",
 +  "asset_ip": "",
 +  "asset_mac": "",
 +  "asset_status": "Deployed",
 +  "asset_purchase_date": "0000-00-00",
 +  "asset_warranty_expire": "0000-00-00",
 +  "install_date": "0000-00-00",
 +  "asset_notes": "",
 +  "asset_vendor_id": "",
 +  "asset_location_id": "",
 +  "asset_contact_id": "",
 +  "asset_network_id": ""
 +}
 +</code>
 +
 +==== Certificates ''/api/v1/certificates/'' ====
 +
 +**Purpose**: SSL/TLS certificate management and expiration tracking
 +
 +**Source**: [[https://docs.itflow.org/certificates|ITFlow Certificates Documentation]]
 +
 +  * ''GET /read.php'' - List/get certificate information
 +  * ''POST /create.php'' - Create certificate record
 +  * ''POST /update.php'' - Update certificate details
 +  * ''POST /delete.php'' - Delete certificate record
 +
 +**Complete Fields** (from ITFlow Certificates API Documentation):
 +
 +<code json>
 +{
 +  "certificate_id": 123,
 +  "client_id": 456,
 +  "certificate_name": "ITFlow Demo",
 +  "certificate_domain": "demo.itflow.org",
 +  "certificate_issued_date": "2024-01-01",
 +  "certificate_expire_date": "2025-01-01",
 +  "certificate_issuer": "Let's Encrypt",
 +  "certificate_public_key": "[Certificate content]",
 +  "certificate_notes": "Auto-renewal enabled"
 +}
 +</code>
 +
 +==== Clients ''/api/v1/clients/'' ====
 +
 +**Purpose**: Customer/company management
 +
 +**Source**: [[https://docs.itflow.org/clients|ITFlow Clients Documentation]]
 +
 +  * ''GET /read.php'' - List/get client information
 +  * ''POST /create.php'' - Create new client
 +  * ''POST /update.php'' - Update client details
 +  * ''POST /delete.php'' - Delete client record
 +
 +**Complete Fields** (from ITFlow Clients API Documentation):
 +
 +<code json>
 +{
 +  "client_id": 111,
 +  "client_lead": 0,
 +  "client_name": "Let it burn Inc",
 +  "client_type": "Safety and Fire",
 +  "client_website": "example.com"
 +}
 +</code>
 +
 +<wrap em>Note: Full field list is partially documented. The API returns numbered keys alongside named keys in the response format.</wrap>
 +
 +==== Contacts ''/api/v1/contacts/'' ====
 +
 +**Purpose**: Individual contact management within client organizations
 +
 +**Source**: ITFlow official API documentation lists contacts as supported module
 +
 +  * ''GET /read.php'' - List/get contact information
 +  * ''POST /create.php'' - Create new contact
 +  * ''POST /update.php'' - Update contact details
 +  * ''POST /delete.php'' - Delete contact record
 +
 +**Available Fields**: Contact table structure includes fields like ''contact_department'' as confirmed by GitHub Issue #458, but complete API field specification is not fully documented.
 +
 +==== Credentials ''/api/v1/credentials/'' ====
 +
 +**Purpose**: Password and login management (encrypted storage)
 +
 +**Source**: ITFlow official API documentation lists credentials (logins) as supported module
 +
 +  * ''GET /read.php'' - List/get credential information
 +  * ''POST /create.php'' - Create new credential record
 +  * ''POST /update.php'' - Update credential details
 +  * ''POST /delete.php'' - Delete credential record
 +
 +**Available Fields**: Database migration scripts confirm ''login_folder_id'' field addition, but complete API field specification requires further documentation.
 +
 +==== Domains ''/api/v1/domains/'' ====
 +
 +**Purpose**: Domain name management and renewal tracking
 +
 +**Source**: [[https://docs.itflow.org/domains|ITFlow Domains Documentation]]
 +
 +  * ''GET /read.php'' - List/get domain information
 +  * ''POST /create.php'' - Create domain record
 +  * ''POST /update.php'' - Update domain details
 +  * ''POST /delete.php'' - Delete domain record
 +
 +**Complete Fields** (from ITFlow Domains API Documentation):
 +
 +<code json>
 +{
 +  "domain_id": 123,
 +  "client_id": 456,
 +  "domain_name": "itflow.org",
 +  "domain_registrar": "GoDaddy",
 +  "domain_webhost": "SiteGround",
 +  "domain_expire": "2025-03-15",
 +  "domain_ip": "192.168.1.1",
 +  "domain_name_servers": "ns1.example.com, ns2.example.com",
 +  "domain_mail_servers": "mx1.example.com",
 +  "domain_notes": "Auto-renewal enabled"
 +}
 +</code>
 +
 +==== Networks ''/api/v1/networks/'' ====
 +
 +**Purpose**: Network infrastructure documentation
 +
 +**Source**: ITFlow official API documentation lists networks as supported module
 +
 +  * ''GET /read.php'' - List/get network information
 +  * ''POST /create.php'' - Create network record
 +  * ''POST /update.php'' - Update network details
 +  * ''POST /delete.php'' - Delete network record
 +
 +**Available Fields**: Database migration scripts show network interface relationships, but complete API field specification requires further documentation.
 +
 +==== Software ''/api/v1/software/'' ====
 +
 +**Purpose**: Software license and application tracking
 +
 +**Source**: ITFlow official API documentation lists software as supported module
 +
 +  * ''GET /read.php'' - List/get software information
 +  * ''POST /create.php'' - Create software record
 +  * ''POST /update.php'' - Update software details
 +  * ''POST /delete.php'' - Delete software record
 +
 +**Status**: Module confirmed as available but dedicated documentation page not found. Database includes software table as confirmed by installation scripts.
 +
 +==== Tickets ''/api/v1/tickets/'' ====
 +
 +**Purpose**: Help desk and issue tracking
 +
 +**Source**: [[https://docs.itflow.org/tickets|ITFlow Tickets Documentation]]
 +
 +  * ''GET /read.php'' - List/get ticket information
 +  * ''POST /create.php'' - Create new ticket
 +  * ''POST /update.php'' - Update ticket details
 +  * ''POST /delete.php'' - Delete ticket record
 +
 +**Complete Fields** (from ITFlow Tickets API Documentation):
 +
 +<code json>
 +{
 +  "ticket_id": 3,
 +  "ticket_prefix": "TCK-",
 +  "ticket_number": 3,
 +  "ticket_category": null,
 +  "ticket_subject": "Computer broken"
 +}
 +</code>
 +
 +<wrap em>Note: Full field list is partially documented. The API returns numbered keys alongside named keys in the response format.</wrap>
 +
 +===== Current API Capabilities =====
 +
 +==== Standard Operations (All Modules) ====
 +
 +  * **READ**: Retrieve single record or list of records
 +  * **CREATE**: Add new records with validation (partial support)
 +  * **UPDATE**: Modify existing records (partial support)
 +  * **DELETE**: Remove records (partial support)
 +
 +==== Query Parameters (read.php endpoints) ====
 +
 +  * ''client_id'' - Filter by specific client
 +  * ''limit'' - Number of records to return (default: 50)
 +  * ''offset'' - Number of records to skip for pagination
 +  * API key required on all requests
 +
 +==== Response Format (Standardized) ====
 +
 +<code json>
 +{
 +  "success": "True|False",
 +  "message": "Descriptive message",
 +  "count": 1,
 +  "data": [
 +    {
 +      // Record data with both numbered and named keys
 +    }
 +  ]
 +}
 +</code>
 +
 +===== Current Authentication =====
 +
 +==== API Key Generation ====
 +
 +  - Navigate to Admin panel in ITFlow
 +  - Click on API section
 +  - Click **New Key** to generate
 +  - Choose scope: specific client or all clients
 +  - Copy generated key for use
 +
 +==== API Key Usage ====
 +
 +  * **Method**: Query parameter
 +  * **Format**: ''?api_key=YOUR_API_KEY''
 +  * **Scope**: Can be limited to specific client or all clients
 +  * **Access**: Currently all-or-nothing permissions
 +
 +==== Security Features ====
 +
 +  * **Encrypted Storage**: API keys stored securely
 +  * **Client Scoping**: Keys can be limited to specific clients
 +  * **Access Logging**: API usage tracked in logs
 +
 +===== Current Limitations =====
 +
 +==== Missing CRUD Operations ====
 +
 +  * **UPDATE**: Limited support across modules
 +  * **DELETE**: Limited support across modules
 +  * **ARCHIVE**: Not implemented
 +
 +==== Missing Advanced Features ====
 +
 +  * **Bulk Operations**: No batch create/update/delete
 +  * **Advanced Search**: No full-text search or complex filtering
 +  * **Webhooks**: No real-time event notifications
 +  * **File Upload**: No direct file management API
 +  * **Relationships**: Limited cross-module data retrieval
 +
 +==== Missing Business Modules ====
 +
 +  * **Invoices/Billing**: No financial transaction APIs
 +  * **Quotes**: No sales proposal management
 +  * **Time Tracking**: No billable hour recording
 +  * **Calendar**: No scheduling or appointment APIs
 +  * **Reports**: No automated report generation
 +
 +==== Authentication Limitations ====
 +
 +  * **Granular Permissions**: No module-specific access control
 +  * **OAuth**: Only API key authentication available
 +
 +===== API Usage Examples =====
 +
 +==== Get All Clients ====
 +
 +<code bash>
 +GET /api/v1/clients/read.php?api_key=YOUR_KEY
 +</code>
 +
 +==== Get Specific Asset ====
 +
 +<code bash>
 +GET /api/v1/assets/read.php?api_key=YOUR_KEY&asset_id=123
 +</code>
 +
 +==== Create New Ticket ====
 +
 +<code bash>
 +POST /api/v1/tickets/create.php
 +Content-Type: application/json
 +
 +{
 +  "api_key": "YOUR_KEY",
 +  "client_id": 456,
 +  "ticket_subject": "Printer offline",
 +  "ticket_details": "Office printer not responding",
 +  "ticket_priority": "Medium"
 +}
 +</code>
 +
 +==== List Client Assets ====
 +
 +<code bash>
 +GET /api/v1/assets/read.php?api_key=YOUR_KEY&client_id=456
 +</code>
 +
 +===== Integration Capabilities =====
 +
 +==== What Works Today ====
 +
 +  * **Basic CRUD**: Create/read operations for core modules
 +  * **Client Management**: Full customer database management
 +  * **Asset Tracking**: Computer and equipment inventory
 +  * **Ticket Creation**: Help desk ticket automation
 +  * **Documentation**: Network, domain, certificate tracking
 +
 +==== What's Missing for Full Automation ====
 +
 +  * **Financial Operations**: No billing/invoicing automation
 +  * **Real-time Events**: No webhook triggers for automation
 +  * **Bulk Data Sync**: No efficient mass data operations
 +  * **File Management**: No document upload/download APIs
 +  * **Advanced Workflows**: No time tracking or scheduling APIs
 +
 +===== Error Handling & Troubleshooting =====
 +
 +==== Standard Error Codes ====
 +
 +**Source**: HTTP standard codes - ITFlow API observed behavior
 +
 +  * **200**: Success - Request completed successfully
 +  * **400**: Bad Request - Invalid parameters or malformed request
 +  * **401**: Unauthorized - Invalid or missing API key
 +  * **403**: Forbidden - API key lacks required permissions
 +  * **404**: Not Found - Endpoint or record doesn't exist
 +  * **500**: Server Error - Internal ITFlow error
 +
 +==== Common Error Messages ====
 +
 +**Source**: Observed API responses
 +
 +<code json>
 +{
 +  "success": "False",
 +  "message": "Invalid API key",
 +  "count": 0,
 +  "data": []
 +}
 +</code>
 +
 +==== Troubleshooting Steps ====
 +
 +**Source**: Community experience and [[https://docs.itflow.org/installation|ITFlow Installation Documentation]]
 +
 +  - **API Key Issues**
 +    * Verify key is correct (copy/paste errors common)
 +    * Check key scope (client-specific vs all clients)
 +    * Confirm key hasn't been deactivated
 +
 +  - **Permission Errors**
 +    * Add ''client_id'' parameter for scoped keys
 +    * Verify client_id exists and is accessible
 +
 +  - **Server Errors**
 +    * Check Apache/PHP error logs: ''/var/log/apache2/error.log''
 +    * Verify ITFlow database connectivity
 +    * Check PHP memory limits for large requests
 +
 +  - **Data Issues**
 +    * Validate required fields for POST requests
 +    * Check data types (strings, integers, dates)
 +    * Verify foreign key relationships exist
 +
 +==== Debug Mode ====
 +
 +**Source**: ITFlow admin settings and [[https://docs.itflow.org/faq|ITFlow FAQ]]
 +
 +Enable PHP error reporting in ITFlow settings for detailed error messages during development.
 +
 +===== Integration Examples =====
 +
 +==== PowerShell Examples ====
 +
 +**Source**: [[https://github.com/itflow-org/itflow-api-powershell|ITFlow PowerShell Repository]]
 +
 +**List All Clients**:
 +
 +<code powershell>
 +$apiKey = "YOUR-API-KEY"
 +$baseUrl = "https://itflow.yourdomain.com"
 +$uri = "$baseUrl/api/v1/clients/read.php?api_key=$apiKey"
 +
 +Invoke-RestMethod -Uri $uri | ConvertTo-Json
 +</code>
 +
 +**Create New Asset**:
 +
 +<code powershell>
 +$uri = "https://itflow.yourdomain.com/api/v1/assets/create.php"
 +$body = @{
 +    "api_key" = "YOUR-API-KEY"
 +    "asset_name" = "Sample Laptop"
 +    "asset_type" = "Laptop"
 +    "asset_make" = "Dell"
 +    "asset_model" = "Optiplex"
 +    "client_id" = "1"
 +} | ConvertTo-Json
 +
 +Invoke-RestMethod -Method Post -Uri $uri -Body $body -ContentType "application/json"
 +</code>
 +
 +==== PHP Examples ====
 +
 +<code php>
 +<?php
 +$api_key = 'YOUR_API_KEY';
 +$base_url = 'https://itflow.yourdomain.com/api/v1/';
 +
 +// Get clients
 +$url = $base_url . 'clients/read.php?api_key=' . $api_key;
 +$response = file_get_contents($url);
 +$data = json_decode($response, true);
 +
 +print_r($data);
 +?>
 +</code>
 +
 +==== Python Examples ====
 +
 +<code python>
 +import requests
 +
 +api_key = "YOUR_API_KEY"
 +base_url = "https://itflow.yourdomain.com/api/v1/"
 +
 +# Get all clients
 +response = requests.get(f"{base_url}clients/read.php?api_key={api_key}")
 +data = response.json()
 +print(data)
 +
 +# Create new ticket
 +ticket_data = {
 +    "api_key": api_key,
 +    "client_id": 456,
 +    "ticket_subject": "Network issue",
 +    "ticket_details": "Unable to access shared drive",
 +    "ticket_priority": "High"
 +}
 +
 +response = requests.post(f"{base_url}tickets/create.php", json=ticket_data)
 +result = response.json()
 +print(result)
 +</code>