# Provider API Reference\n\nAPI documentation for creating and using infrastructure providers.\n\n## Overview\n\nProviders handle cloud-specific operations and resource provisioning. The provisioning platform supports multiple cloud providers through a unified API.\n\n## Supported Providers\n\n- **UpCloud** - European cloud provider\n- **AWS** - Amazon Web Services\n- **Local** - Local development environment\n\n## Provider Interface\n\nAll providers must implement the following interface:\n\n### Required Functions\n\n```\n# Provider initialization\nexport def init [] -> record { ... }\n\n# Server operations\nexport def create-servers [plan: record] -> list { ... }\nexport def delete-servers [ids: list] -> bool { ... }\nexport def list-servers [] -> table { ... }\n\n# Resource information\nexport def get-server-plans [] -> table { ... }\nexport def get-regions [] -> list { ... }\nexport def get-pricing [plan: string] -> record { ... }\n```\n\n### Provider Configuration\n\nEach provider requires configuration in Nickel format:\n\n```\n# Example: UpCloud provider configuration\n{\n  provider = {\n    name = "upcloud",\n    type = "cloud",\n    enabled = true,\n    config = {\n      username = "{{env.UPCLOUD_USERNAME}}",\n      password = "{{env.UPCLOUD_PASSWORD}}",\n      default_zone = "de-fra1",\n    },\n  }\n}\n```\n\n## Creating a Custom Provider\n\n### 1. Directory Structure\n\n```\nprovisioning/extensions/providers/my-provider/\n├── nulib/\n│   └── my_provider.nu          # Provider implementation\n├── schemas/\n│   ├── main.ncl                # Nickel schema\n│   └── defaults.ncl            # Default configuration\n└── README.md                   # Provider documentation\n```\n\n### 2. Implementation Template\n\n```\n# my_provider.nu\nexport def init [] {\n    {\n        name: "my-provider"\n        type: "cloud"\n        ready: true\n    }\n}\n\nexport def create-servers [plan: record] {\n    # Implementation here\n    []\n}\n\nexport def list-servers [] {\n    # Implementation here\n    []\n}\n\n# ... other required functions\n```\n\n### 3. Nickel Schema\n\n```\n# main.ncl\n{\n  MyProvider = {\n    # My custom provider schema\n    name | String = "my-provider",\n    type | String | "cloud" | "local" = "cloud",\n    config | MyProviderConfig,\n  },\n\n  MyProviderConfig = {\n    api_key | String,\n    region | String = "us-east-1",\n  },\n}\n```\n\n## Provider Discovery\n\nProviders are automatically discovered from:\n\n- `provisioning/extensions/providers/*/nu/*.nu`\n- User workspace: `workspace/extensions/providers/*/nu/*.nu`\n\n```\n# Discover available providers\nprovisioning module discover providers\n\n# Load provider\nprovisioning module load providers workspace my-provider\n```\n\n## Provider API Examples\n\n### Create Servers\n\n```\nuse my_provider.nu *\n\nlet plan = {\n    count: 3\n    size: "medium"\n    zone: "us-east-1"\n}\n\ncreate-servers $plan\n```\n\n### List Servers\n\n```\nlist-servers | where status == "running" | select hostname ip_address\n```\n\n### Get Pricing\n\n```\nget-pricing "small" | to yaml\n```\n\n## Testing Providers\n\nUse the test environment system to test providers:\n\n```\n# Test provider without real resources\nprovisioning test env single my-provider --check\n```\n\n## Provider Development Guide\n\nFor complete provider development guide, see:\n\n- **[Provider Development](../development/QUICK_PROVIDER_GUIDE.md)** - Quick start guide\n- **[Extension Development](../development/extensions.md)** - Complete extension guide\n- **[Integration Examples](integration-examples.md)** - Example implementations\n\n## API Stability\n\nProvider API follows semantic versioning:\n\n- **Major**: Breaking changes\n- **Minor**: New features, backward compatible\n- **Patch**: Bug fixes\n\nCurrent API version: `2.0.0`\n\n---\n\nFor more examples, see [Integration Examples](integration-examples.md).
