Initial commit: add .gitignore and README

API_DOCUMENTATION.md

@@ -0,0 +1,85 @@
+# Omada Cloud Northbound API Documentation
+
+## Official API Documentation
+
+The Omada Cloud northbound API documentation is available at:
+- **EU Region**: https://euw1-omada-northbound.tplinkcloud.com/doc.html#/home
+- **US Region**: https://usw1-omada-northbound.tplinkcloud.com/doc.html#/home
+- **Asia Region**: https://ap1-omada-northbound.tplinkcloud.com/doc.html#/home
+
+## API Base URL Structure
+
+Our implementation uses:
+```
+${OMADA_NORTHBOUND_BASE}/openapi/v1/omada/${OMADA_ID}
+```
+
+Example:
+```
+https://euw1-omada-northbound.tplinkcloud.com/openapi/v1/omada/b7335e3ad40ef0df060a922dcf5abdf5
+```
+
+## Authentication
+
+The API documentation should contain the correct authentication endpoint. Based on our implementation, we're trying:
+
+1. `${OMADA_CONTROLLER_BASE}/${OMADA_ID}/openapi/login`
+2. `${OMADA_CONTROLLER_BASE}/openapi/login`
+3. `${OMADA_NORTHBOUND_BASE}/openapi/v1/omada/${OMADA_ID}/login`
+
+**Note**: Check the official documentation for the exact authentication endpoint format.
+
+## API Endpoints Used
+
+### Sites
+- `GET /sites` - List all sites
+- `GET /sites/{siteId}` - Get site details
+
+### Devices
+- `GET /sites/{siteId}/devices` - List devices for a site
+- `GET /sites/{siteId}/devices/{deviceId}` - Get device details
+- `POST /sites/{siteId}/devices/{deviceId}/reboot` - Reboot device
+- `POST /sites/{siteId}/devices/{deviceId}/locate` - Locate device
+
+### Gateway Configuration
+- `GET /sites/{siteId}/devices/{deviceId}/wan` - Get WAN configuration
+- `PUT /sites/{siteId}/devices/{deviceId}/wan` - Update WAN configuration
+- `POST /sites/{siteId}/devices/{deviceId}/vpn` - Configure VPN
+
+### Switch Configuration
+- `GET /sites/{siteId}/devices/{deviceId}/ports` - Get switch ports
+- `POST /sites/{siteId}/devices/{deviceId}/ports/{portIndex}/vlan` - Set port VLAN
+- `PUT /sites/{siteId}/devices/{deviceId}/ports/{portIndex}` - Toggle port
+
+### Wireless (SSID)
+- `GET /sites/{siteId}/wlans` - List SSIDs
+- `POST /sites/{siteId}/wlans` - Create SSID
+- `PUT /sites/{siteId}/wlans/{wlanId}` - Update SSID
+
+### Clients
+- `GET /sites/{siteId}/clients` - List clients
+- `POST /sites/{siteId}/clients/{clientId}/block` - Block client
+- `POST /sites/{siteId}/clients/{clientId}/unblock` - Unblock client
+
+## Verifying Endpoints
+
+To verify the correct endpoint structure:
+1. Visit the API documentation URL for your region
+2. Check the authentication endpoint format
+3. Verify the endpoint paths match our implementation
+4. Update our code if the documentation shows different paths
+
+## Accessing the Documentation
+
+You can access the interactive API documentation by:
+1. Opening the doc.html URL in your browser
+2. Using the Swagger UI interface to explore endpoints
+3. Testing endpoints directly from the documentation interface (if authentication is configured)
+
+## Next Steps
+
+1. Review the official documentation for authentication endpoint
+2. Verify all endpoint paths match the documentation
+3. Update implementation if discrepancies are found
+4. Test endpoints using the documentation interface
+