From 499e07068c7eaff10af17d2f5226d9df5392d786 Mon Sep 17 00:00:00 2001 From: lauren Date: Tue, 11 Nov 2025 11:21:25 -0600 Subject: [PATCH] docs: Add comprehensive API endpoint documentation - Add new API.md with complete endpoint documentation - Document all 6 API endpoints with request/response examples - Include authentication, error handling, and usage examples - Update docs/README.md to link to API documentation --- docs/API.md | 388 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 5 + 2 files changed, 393 insertions(+) create mode 100644 docs/API.md diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..09b49f9 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,388 @@ +# Polydock Engine API Documentation + +This document describes the REST API endpoints available in Polydock Engine. + +## Base URL + +All API endpoints are prefixed with `/api`. For example: +- Production: `https://your-domain.com/api` +- Local Development: `http://localhost/api` + +## Authentication + +Most endpoints do not require authentication. The `/api/user` endpoint requires Laravel Sanctum authentication via bearer token or session cookie. + +## Endpoints + +### 1. Get Current User + +Retrieve information about the currently authenticated user. + +**Endpoint:** `GET /api/user` + +**Authentication:** Required (Sanctum) + +**Response:** +```json +{ + "id": 1, + "name": "John Doe", + "email": "john@example.com", + ... +} +``` + +**Status Codes:** +- `200 OK` - User retrieved successfully +- `401 Unauthorized` - Authentication required + +--- + +### 2. Register User + +Create a new user registration request. This endpoint accepts registration data and creates a pending registration that will be processed asynchronously. + +**Endpoint:** `POST /api/register` + +**Authentication:** Not required + +**Request Body:** +```json +{ + "email": "user@example.com", + "region_id": 1, + "app_uuid": "550e8400-e29b-41d4-a716-446655440000", + "privacy_policy_accepted": true, + "aup_accepted": true, + ... +} +``` + +**Request Parameters:** +- `email` (string, required) - User's email address +- Additional fields may be accepted and stored in `request_data` + +**Response:** +```json +{ + "status": "pending", + "message": "Registration pending", + "id": "550e8400-e29b-41d4-a716-446655440000" +} +``` + +**Status Codes:** +- `202 Accepted` - Registration request created successfully +- `500 Internal Server Error` - Error creating registration + +**Notes:** +- The registration is processed asynchronously +- Use the returned `id` (UUID) to check registration status via the `GET /api/register/{uuid}` endpoint +- All request data is stored and can be retrieved later + +--- + +### 3. Get Registration Status + +Retrieve the status and details of a user registration by UUID. + +**Endpoint:** `GET /api/register/{uuid}` + +**Authentication:** Not required + +**URL Parameters:** +- `uuid` (string, required) - The UUID of the registration + +**Response:** +```json +{ + "status": "success", + "email": "user@example.com", + "result_data": { + "app_instance_uuid": "550e8400-e29b-41d4-a716-446655440001", + "app_url": "https://app.example.com", + "message": "Registration completed successfully" + }, + "created_at": "2024-01-15T10:30:00.000000Z", + "updated_at": "2024-01-15T10:35:00.000000Z" +} +``` + +**Status Values:** +- `pending` - Registration is pending processing +- `processing` - Registration is currently being processed +- `success` - Registration completed successfully +- `failed` - Registration failed + +**Status Codes:** +- `200 OK` - Registration found and returned +- `404 Not Found` - Registration with the provided UUID not found + +**Notes:** +- The `result_data` field contains additional information about the registration result, such as app instance details +- If the associated app instance has failed, the registration status will automatically be updated to `failed` + +--- + +### 4. Get Regions and Apps + +Retrieve all public regions (stores) and their available apps. This endpoint is useful for displaying available regions and applications in a marketplace or registration interface. + +**Endpoint:** `GET /api/regions` + +**Authentication:** Not required + +**Response:** +```json +{ + "status": "success", + "message": "Regions and apps retrieved successfully", + "data": { + "regions": [ + { + "uuid": null, + "id": 1, + "label": "US East", + "apps": [ + { + "uuid": "550e8400-e29b-41d4-a716-446655440000", + "label": "My Application" + } + ] + }, + { + "uuid": null, + "id": 2, + "label": "EU West", + "apps": [ + { + "uuid": "550e8400-e29b-41d4-a716-446655440001", + "label": "Another Application" + } + ] + } + ] + }, + "status_code": 200 +} +``` + +**Response Fields:** +- `regions` (array) - List of public regions/stores + - `id` (integer) - Region/store ID + - `label` (string) - Display name of the region + - `apps` (array) - List of available apps in this region + - `uuid` (string) - App UUID + - `label` (string) - Display name of the app + +**Status Codes:** +- `200 OK` - Regions and apps retrieved successfully +- `500 Internal Server Error` - Error retrieving regions + +**Notes:** +- Only returns regions with `status = PUBLIC` and `listed_in_marketplace = true` +- Only returns apps with `status = AVAILABLE` +- Regions use `id` as identifier (not UUID) + +--- + +### 5. Update Instance Health Status + +Update the health status of a Polydock app instance. This endpoint accepts both GET and POST requests and is typically called by health check systems or deployment scripts. + +**Endpoint:** `GET|POST /api/instance/{uuid}/health/{status}` + +**Authentication:** Not required + +**URL Parameters:** +- `uuid` (string, required) - The UUID of the app instance +- `status` (string, required) - The health status to set + +**Query Parameters (GET) or Request Body (POST):** +- Optional debug data can be included and will be logged + +**Valid Status Values:** +- `running_healthy_claimed` - Instance is running, healthy, and claimed by a user +- `running_healthy_unclaimed` - Instance is running, healthy, but not yet claimed +- `running_unhealthy` - Instance is running but unhealthy +- `running_unresponsive` - Instance is running but not responding + +**Prerequisites:** +The instance must be in one of the following states before a health status update is allowed: +- `running_healthy_claimed` +- `running_healthy_unclaimed` +- `running_unhealthy` +- `running_unresponsive` +- `post_deploy_completed` +- `post_upgrade_completed` + +**Response:** +```json +{ + "message": "Health status updated successfully", + "instance": "550e8400-e29b-41d4-a716-446655440000", + "status": "running_healthy_claimed", + "status_code": 200 +} +``` + +**Status Codes:** +- `200 OK` - Health status updated successfully +- `400 Bad Request` - Invalid status value or instance not ready for health check update +- `404 Not Found` - Instance with the provided UUID not found + +**Error Responses:** + +Invalid status value: +```json +{ + "error": "Invalid status value", + "status_code": 400 +} +``` + +Invalid running status: +```json +{ + "error": "Invalid running status", + "status_code": 400, + "allowed_statuses": [ + "running_healthy_claimed", + "running_healthy_unclaimed", + "running_unhealthy", + "running_unresponsive" + ] +} +``` + +Instance not ready for health check: +```json +{ + "error": "Current status is not ready for health check update", + "status_code": 400 +} +``` + +**Notes:** +- Both GET and POST methods are supported +- Debug data can be included in query parameters (GET) or request body (POST) and will be logged +- The endpoint validates that the status transition is allowed based on the current instance state + +--- + +## Web Routes + +### 6. Redirect to App Instance + +Redirect to an app instance's URL. This route checks for a one-time login URL first, then falls back to the app URL. + +**Endpoint:** `GET /app-instances/{appInstance}` + +**Authentication:** Not required + +**URL Parameters:** +- `appInstance` (integer|string) - The ID or UUID of the app instance + +**Response:** +- `302 Found` - Redirects to the app instance URL +- `404 Not Found` - No URL available for this app instance + +**Notes:** +- If a one-time login URL exists and hasn't expired, it will be used +- Otherwise, the app URL will be used +- If neither URL is available, a 404 error is returned + +--- + +## Error Handling + +All endpoints follow standard HTTP status codes: + +- `200 OK` - Request successful +- `202 Accepted` - Request accepted for processing +- `400 Bad Request` - Invalid request parameters +- `401 Unauthorized` - Authentication required +- `404 Not Found` - Resource not found +- `500 Internal Server Error` - Server error + +Error responses typically include: +```json +{ + "error": "Error message", + "status_code": 400 +} +``` + +Or for registration endpoints: +```json +{ + "status": "error", + "message": "Error message" +} +``` + +--- + +## Rate Limiting + +Rate limiting may be applied to API endpoints. Check response headers for rate limit information: +- `X-RateLimit-Limit` - Maximum number of requests allowed +- `X-RateLimit-Remaining` - Number of requests remaining +- `Retry-After` - Seconds to wait before retrying (if rate limited) + +--- + +## Examples + +### Register a New User + +```bash +curl -X POST https://your-domain.com/api/register \ + -H "Content-Type: application/json" \ + -d '{ + "email": "user@example.com", + "region_id": 1, + "app_uuid": "550e8400-e29b-41d4-a716-446655440000", + "privacy_policy_accepted": true, + "aup_accepted": true + }' +``` + +### Check Registration Status + +```bash +curl https://your-domain.com/api/register/550e8400-e29b-41d4-a716-446655440000 +``` + +### Get Available Regions and Apps + +```bash +curl https://your-domain.com/api/regions +``` + +### Update Instance Health Status + +```bash +# Using GET +curl "https://your-domain.com/api/instance/550e8400-e29b-41d4-a716-446655440000/health/running_healthy_claimed?debug_info=some_data" + +# Using POST +curl -X POST https://your-domain.com/api/instance/550e8400-e29b-41d4-a716-446655440000/health/running_healthy_claimed \ + -H "Content-Type: application/json" \ + -d '{ + "debug_info": "some_data" + }' +``` + +--- + +## Versioning + +Currently, there is no API versioning in place. All endpoints are under `/api`. Future versions may introduce versioned endpoints (e.g., `/api/v1/...`). + +--- + +## Support + +For questions or issues with the API, please contact the development team or refer to the main [Documentation](README.md). + diff --git a/docs/README.md b/docs/README.md index 805b74d..708c0ea 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,11 @@ Polydock Engine is a Laravel-based application management and deployment platform that enables organizations to offer self-service trials and deployments of their applications on top of [Lagoon](https://www.lagoon.sh) platforms (such as [amazee.io](https://www.amazee.io)). While Lagoon empowers developers to use Kubernetes without deep technical knowledge, Polydock Engine focuses on enabling non-technical users to deploy and manage multiple instances of the same application through a user-friendly interface. +## Documentation + +- **[API Documentation](API.md)** - Complete REST API endpoint reference +- **[Architecture Documentation](ARCHITECTURE/README.md)** - System architecture and design details + ## Implemented Features ### Application Management