API Overview & Authentication

The UncleBTech API provides programmatic access to manage your hosting services, domains, billing, and support tickets. This guide covers API basics, authentication, and getting started with your first API requests.

API Basics

Base URL and Versioning

API Base URL:

https://api.uncleb.tech/v1

API Versioning:

• Current Version: v1 (stable)
• Version Header: Accept: application/vnd.unclebtech.v1+json
• Backward Compatibility: v1 will remain stable with backward compatibility
• Future Versions: New versions will be announced with migration guides

API Architecture

RESTful Design:

• HTTP Methods: GET, POST, PUT, DELETE for different operations
• Resource-Based URLs: URLs represent resources (services, domains, invoices)
• Status Codes: Standard HTTP status codes for response indication
• JSON Format: All requests and responses use JSON format

Request/Response Format:

# Request headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer your-api-key

# Response format
{
  "success": true,
  "data": { ... },
  "meta": {
    "pagination": { ... },
    "rate_limit": { ... }
  }
}

Authentication

API Key Authentication

Generating API Keys:

1. Log into your client portal at https://my.uncleb.tech
2. Navigate to "Account Settings" → "API Access"
3. Click "Generate New API Key"
4. Set permissions and access levels:
   • Read Only: View information only
   • Read/Write: Full access to manage resources
   • Billing: Access to billing and payment information
   • Support: Access to support ticket management
5. Copy and securely store your API key

API Key Usage:

# Using API key in requests
curl -H "Authorization: Bearer your-api-key" \
     -H "Content-Type: application/json" \
     https://api.uncleb.tech/v1/services

API Key Management

Security Best Practices:

• Secure Storage: Store API keys securely, never in public repositories
• Key Rotation: Regularly rotate API keys for security
• Minimal Permissions: Use least-privilege principle for API key permissions
• Monitor Usage: Regularly monitor API key usage and access logs

Key Management Operations:

# List API keys
GET /api/v1/account/api-keys

# Create new API key
POST /api/v1/account/api-keys
{
  "name": "Production API Key",
  "permissions": ["read", "write"],
  "expires_at": "2025-12-31T23:59:59Z"
}

# Revoke API key
DELETE /api/v1/account/api-keys/{key_id}

Authentication Errors

Common Authentication Issues:

• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: API key lacks required permissions
• 429 Too Many Requests: Rate limit exceeded
• Invalid Key Format: Malformed authorization header

Error Response Format:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has expired",
    "details": {
      "key_id": "key_123456",
      "expires_at": "2025-01-01T00:00:00Z"
    }
  }
}

Rate Limits and Quotas

Rate Limiting

Default Rate Limits:

• Standard API Keys: 1000 requests per hour
• Premium API Keys: 5000 requests per hour
• Burst Allowance: 100 requests per minute
• Reset Period: Rate limits reset every hour

Rate Limit Headers:

# Response headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 3600

Handling Rate Limits

Best Practices:

• Implement Backoff: Use exponential backoff for rate limit errors
• Cache Responses: Cache API responses to reduce request frequency
• Batch Operations: Use batch endpoints where available
• Monitor Usage: Track your API usage to avoid hitting limits

Rate Limit Error Handling:

# Example rate limit handling
if response.status_code == 429:
    retry_after = response.headers.get('X-RateLimit-Retry-After')
    time.sleep(int(retry_after))
    # Retry the request

Making Your First API Request

Authentication Test

Test API Key:

# Test your API key
curl -H "Authorization: Bearer your-api-key" \
     -H "Accept: application/json" \
     https://api.uncleb.tech/v1/account

# Expected response
{
  "success": true,
  "data": {
    "id": "acc_123456",
    "email": "user@example.com",
    "name": "John Smith",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

Basic Service Listing

List Your Services:

# Get all services
curl -H "Authorization: Bearer your-api-key" \
     -H "Accept: application/json" \
     https://api.uncleb.tech/v1/services

# Response format
{
  "success": true,
  "data": [
    {
      "id": "svc_123456",
      "type": "wordpress_hosting",
      "name": "My WordPress Site",
      "status": "active",
      "plan": "advanced",
      "domain": "example.com",
      "created_at": "2025-01-01T00:00:00Z",
      "expires_at": "2025-12-31T23:59:59Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Error Handling

Standard Error Response:

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested service could not be found",
    "details": {
      "service_id": "svc_invalid",
      "suggestion": "Check the service ID and try again"
    }
  }
}

HTTP Status Codes:

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

API Response Format

Standard Response Structure

Successful Response:

{
  "success": true,
  "data": {
    // Resource data or array of resources
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 100,
      "total_pages": 5
    },
    "rate_limit": {
      "limit": 1000,
      "remaining": 999,
      "reset_at": "2025-01-21T15:00:00Z"
    }
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": {
      "field_errors": {
        "email": ["Email address is required"],
        "domain": ["Domain name is invalid"]
      }
    }
  }
}

Pagination

Paginated Endpoints:

# Request with pagination
GET /api/v1/services?page=2&per_page=50

# Pagination metadata
"meta": {
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": true
  }
}

API Endpoints Overview

Core Resource Endpoints

Account Management:

GET    /api/v1/account              # Get account information
PUT    /api/v1/account              # Update account information
GET    /api/v1/account/usage        # Get resource usage statistics

Service Management:

GET    /api/v1/services             # List all services
GET    /api/v1/services/{id}        # Get specific service details
POST   /api/v1/services             # Create new service
PUT    /api/v1/services/{id}        # Update service configuration
DELETE /api/v1/services/{id}        # Cancel service

Domain Management:

GET    /api/v1/domains              # List all domains
GET    /api/v1/domains/{domain}     # Get domain details
POST   /api/v1/domains              # Register new domain
PUT    /api/v1/domains/{domain}     # Update domain settings
GET    /api/v1/domains/{domain}/dns # Get DNS records
POST   /api/v1/domains/{domain}/dns # Create DNS record

Billing and Invoices:

GET    /api/v1/invoices             # List invoices
GET    /api/v1/invoices/{id}        # Get invoice details
POST   /api/v1/invoices/{id}/pay    # Pay invoice
GET    /api/v1/payments             # List payment history

Support and Tickets

Support Ticket Management:

GET    /api/v1/tickets              # List support tickets
GET    /api/v1/tickets/{id}         # Get ticket details
POST   /api/v1/tickets              # Create new ticket
PUT    /api/v1/tickets/{id}         # Update ticket
POST   /api/v1/tickets/{id}/reply   # Reply to ticket

SDK and Libraries

Official SDKs

Available SDKs:

• PHP SDK: Composer package for PHP applications
• Node.js SDK: NPM package for JavaScript/TypeScript applications
• Python SDK: PyPI package for Python applications
• Go SDK: Go module for Go applications

PHP SDK Example:

<?php
use UncleBTech\API\Client;

$client = new Client('your-api-key');

// List services
$services = $client->services()->list();

// Get service details
$service = $client->services()->get('svc_123456');

// Create new service
$newService = $client->services()->create([
    'type' => 'wordpress_hosting',
    'plan' => 'advanced',
    'domain' => 'example.com'
]);

Node.js SDK Example:

const { UncleBTechAPI } = require('@unclebtech/api');

const client = new UncleBTechAPI('your-api-key');

// List services
const services = await client.services.list();

// Get service details
const service = await client.services.get('svc_123456');

// Create new service
const newService = await client.services.create({
  type: 'wordpress_hosting',
  plan: 'advanced',
  domain: 'example.com'
});

Community Libraries

Third-Party Libraries:

• Ruby Gem: Community-maintained Ruby library
• .NET Library: Community-maintained .NET library
• Rust Crate: Community-maintained Rust library
• Community Support: Community forum for library support and development

API Testing and Development

Testing Tools

Recommended Tools:

• Postman: GUI tool for API testing and development
• Insomnia: Alternative GUI tool for API testing
• curl: Command-line tool for quick API testing
• HTTPie: User-friendly command-line HTTP client

Postman Collection:

{
  "info": {
    "name": "UncleBTech API",
    "description": "Complete UncleBTech API collection"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  }
}

Development Environment Setup

Environment Variables:

# .env file for development
UNCLEBTECH_API_KEY=your-api-key
UNCLEBTECH_API_URL=https://api.uncleb.tech/v1
UNCLEBTECH_ENVIRONMENT=development

Testing Configuration:

# Test API connectivity
curl -H "Authorization: Bearer $UNCLEBTECH_API_KEY" \
     -H "Accept: application/json" \
     $UNCLEBTECH_API_URL/account

API Best Practices

Request Optimization

Efficient API Usage:

1. Use Pagination: Don't request all data at once
2. Filter Results: Use query parameters to filter responses
3. Cache Responses: Cache API responses where appropriate
4. Batch Operations: Use batch endpoints for multiple operations
5. Conditional Requests: Use ETags and conditional requests

Query Parameters:

# Filtering and pagination
GET /api/v1/services?type=wordpress_hosting&status=active&page=1&per_page=50

# Sorting
GET /api/v1/invoices?sort=created_at&order=desc

# Field selection
GET /api/v1/services?fields=id,name,status,expires_at

Error Handling

Robust Error Handling:

// Example error handling in JavaScript
async function makeAPIRequest(endpoint, options = {}) {
  try {
    const response = await fetch(`https://api.uncleb.tech/v1${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      },
      ...options
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.error.message}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Security Considerations

API Security Best Practices:

1. Secure Key Storage: Never expose API keys in client-side code
2. HTTPS Only: Always use HTTPS for API requests
3. Key Rotation: Regularly rotate API keys
4. Minimal Permissions: Use API keys with minimal required permissions
5. Monitor Usage: Monitor API usage for suspicious activity

Security Warning: Never include API keys in client-side JavaScript, mobile apps, or public repositories. API keys should only be used in secure server-side environments.

Webhooks Overview

Webhook Events

Available Events:

• Service Events: service.created, service.suspended, service.cancelled
• Domain Events: domain.registered, domain.transferred, domain.expired
• Billing Events: invoice.created, payment.succeeded, payment.failed
• Support Events: ticket.created, ticket.updated, ticket.closed

Webhook Configuration:

# Configure webhook endpoint
POST /api/v1/webhooks
{
  "url": "https://your-app.com/webhooks/unclebtech",
  "events": ["payment.failed", "service.suspended"],
  "secret": "your-webhook-secret"
}

Webhook Security

Webhook Verification:

<?php
// Verify webhook signature
function verifyWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($signature, $expectedSignature);
}

// Process webhook
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_UNCLEBTECH_SIGNATURE'];

if (verifyWebhookSignature($payload, $signature, $webhookSecret)) {
    $event = json_decode($payload, true);
    // Process the webhook event
}

API Documentation and Resources

Interactive Documentation

API Explorer:

• Swagger UI: Interactive API documentation at https://api.uncleb.tech/docs
• Try It Out: Test API endpoints directly from documentation
• Code Examples: Automatic code generation in multiple languages
• Schema Documentation: Detailed schema documentation for all endpoints

Code Examples

Common Operations:

# Create WordPress hosting service
curl -X POST https://api.uncleb.tech/v1/services \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wordpress_hosting",
    "plan": "advanced",
    "domain": "example.com",
    "billing_cycle": "monthly"
  }'

# Update DNS record
curl -X PUT https://api.uncleb.tech/v1/domains/example.com/dns/123 \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "value": "192.168.1.100",
    "ttl": 3600
  }'

# Pay invoice
curl -X POST https://api.uncleb.tech/v1/invoices/inv_123456/pay \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pm_card_123456"
  }'

API Monitoring and Debugging

Request Logging

Debug Information:

# Enable verbose output for debugging
curl -v -H "Authorization: Bearer your-api-key" \
     https://api.uncleb.tech/v1/services

# Request ID for support
X-Request-ID: req_123456789

API Status and Health

API Health Check:

# Check API health
GET /api/v1/health

# Response
{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "uptime": "99.99%",
    "response_time": "45ms"
  }
}

Monitoring API Usage

Usage Analytics:

# Get API usage statistics
GET /api/v1/account/api-usage

# Response
{
  "success": true,
  "data": {
    "current_period": {
      "requests": 1250,
      "limit": 5000,
      "reset_at": "2025-01-21T15:00:00Z"
    },
    "daily_usage": [
      {"date": "2025-01-20", "requests": 145},
      {"date": "2025-01-19", "requests": 203}
    ]
  }
}

Getting API Support

API Support Channels

Developer Support:

• Email: api@uncleb.tech for API-specific questions
• Documentation: Comprehensive API documentation and guides
• Community Forum: Developer community for API discussions
• GitHub Issues: Report API bugs and feature requests

Support Response Times:

• API Issues: 4-hour response for API-related problems
• Documentation: 24-hour response for documentation questions
• Feature Requests: Reviewed monthly for roadmap planning
• Bug Reports: Immediate attention for critical API bugs

Information to Provide

When Contacting API Support:

• Request ID: Include X-Request-ID header from failed requests
• API Key ID: Provide API key ID (not the actual key)
• Endpoint: Specific API endpoint experiencing issues
• Request/Response: Full request and response details
• Expected Behavior: What you expected to happen
• Actual Behavior: What actually happened

API Status and Updates

Staying Informed:

• API Status Page: Monitor API uptime and performance
• Developer Newsletter: Monthly updates on API changes and new features
• Changelog: Detailed changelog for all API updates
• Migration Guides: Guides for major API version changes

Developer Tip: Start with read-only operations to familiarize yourself with the API structure before implementing write operations. Use the interactive documentation to test endpoints and understand response formats.

Advanced API Features

Batch Operations

Batch Requests:

# Batch multiple operations
POST /api/v1/batch
{
  "requests": [
    {
      "method": "GET",
      "url": "/services/svc_123456"
    },
    {
      "method": "PUT",
      "url": "/services/svc_123456",
      "body": {"plan": "premium"}
    }
  ]
}

Async Operations

Long-Running Operations:

# Start async operation
POST /api/v1/services/svc_123456/migrate
{
  "source": "current-host.com",
  "credentials": { ... }
}

# Response with operation ID
{
  "success": true,
  "data": {
    "operation_id": "op_123456",
    "status": "pending",
    "estimated_completion": "2025-01-21T16:00:00Z"
  }
}

# Check operation status
GET /api/v1/operations/op_123456

Custom Integrations

Integration Examples:

• Billing System Integration: Sync invoices and payments with your accounting system
• Monitoring Integration: Integrate service status with your monitoring dashboard
• Automation Scripts: Automate routine tasks like service provisioning
• Custom Dashboards: Build custom dashboards using API data

---

Ready to start using the UncleBTech API? Generate your first API key in the client portal and explore our interactive documentation at https://api.uncleb.tech/docs for hands-on testing and examples.