Skip to content

README.md

Latest commit

 

History

History
269 lines (207 loc) · 6.22 KB

README.md

File metadata and controls

269 lines (207 loc) · 6.22 KB

platform-java REST API

HTTP REST API server for platform-java management using JDK's built-in com.sun.net.httpserver.

Overview

The platform-java-rest-api module provides a complete HTTP REST API for managing platform-java instances. It offers programmatic access to deployment, lifecycle management, and metrics retrieval.

Features

  • Full CRUD Operations: Deploy, list, start, stop, undeploy applications
  • Metrics Retrieval: Get real-time resource usage (CPU, memory, threads)
  • Status Monitoring: Query application states and health
  • JSON API: Request and response bodies use JSON format
  • Lightweight: Uses JDK's built-in HTTP server (no external dependencies)
  • Authentication: Optional API key authentication via ApiAuthFilter

API Endpoints

Application Management

Method Endpoint Description
POST /api/applications Deploy a new application
GET /api/applications List all applications
GET /api/applications/{id} Get application details
GET /api/applications/{id}/status Get application status and metrics
POST /api/applications/{id}/start Start an application
POST /api/applications/{id}/stop Stop an application
DELETE /api/applications/{id} Undeploy an application
GET /api/applications/{id}/metrics Get resource metrics history

Platform Management

Method Endpoint Description
GET /api/platform/status Get platform status and summary
GET /api/platform/health Health check endpoint

Usage

Starting the API Server

import org.flossware.platform-java.api.PlatformManager;
import org.flossware.platform-java.core.ApplicationManager;
import org.flossware.platform-java.rest.JdkHttpApiServer;

public class Main {
    public static void main(String[] args) throws IOException {
        PlatformManager manager = new ApplicationManager();
        JdkHttpApiServer server = new JdkHttpApiServer(manager, 8080);
        server.start();
        
        System.out.println("API server running on http://localhost:8080");
    }
}

Deploy Application

curl -X POST http://localhost:8080/api/applications \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "my-app",
    "name": "My Application",
    "mainClass": "com.example.MyApp",
    "classpathEntries": ["file:///path/to/app.jar"],
    "threadPool": {
      "corePoolSize": 4,
      "maxPoolSize": 20
    }
  }'

Response (201 Created):

{
  "applicationId": "my-app",
  "name": "My Application",
  "mainClass": "com.example.MyApp",
  "state": "DEPLOYED",
  "deployedAt": "2024-05-24T10:30:00Z",
  "metrics": {
    "cpuTimeNanos": 0,
    "heapUsedBytes": 0,
    "threadCount": 0
  }
}

List Applications

curl http://localhost:8080/api/applications

Response (200 OK):

[
  {
    "applicationId": "my-app",
    "name": "My Application",
    "mainClass": "com.example.MyApp",
    "state": "DEPLOYED",
    "deployedAt": "2024-05-24T10:30:00Z",
    "metrics": { ... }
  }
]

Start Application

curl -X POST http://localhost:8080/api/applications/my-app/start

Response (200 OK):

{
  "applicationId": "my-app",
  "state": "RUNNING",
  ...
}

Get Application Status

curl http://localhost:8080/api/applications/my-app/status

Response (200 OK):

{
  "applicationId": "my-app",
  "state": "RUNNING",
  "deployedAt": "2024-05-24T10:30:00Z",
  "metrics": {
    "cpuTimeNanos": 1234567890,
    "heapUsedBytes": 52428800,
    "threadCount": 15
  }
}

Stop Application

curl -X POST http://localhost:8080/api/applications/my-app/stop

Response (200 OK)

Undeploy Application

curl -X DELETE http://localhost:8080/api/applications/my-app

Response (204 No Content)

Get Platform Status

curl http://localhost:8080/api/platform/status

Response (200 OK):

{
  "totalApplications": 3,
  "runningApplications": 2,
  "stoppedApplications": 1,
  "failedApplications": 0,
  "uptime": "2h 15m 30s"
}

Error Responses

All errors return a consistent JSON structure:

{
  "error": "Application not found",
  "status": 404,
  "timestamp": "2024-05-24T10:30:00Z"
}

Common status codes:

  • 400 - Bad Request (invalid JSON, missing required fields)
  • 404 - Not Found (application does not exist)
  • 409 - Conflict (application already exists, invalid state transition)
  • 500 - Internal Server Error

Authentication

Enable API key authentication:

JdkHttpApiServer server = new JdkHttpApiServer(manager, 8080);
server.setApiKey("your-secret-api-key");
server.start();

Clients must include the API key in the X-API-Key header:

curl -H "X-API-Key: your-secret-api-key" \
  http://localhost:8080/api/applications

Configuration

Port

Default port is 8080. Override in constructor:

JdkHttpApiServer server = new JdkHttpApiServer(manager, 9090);

CORS

CORS is enabled by default for all origins. To restrict:

// Custom CORS configuration requires modifying ApiAuthFilter

Components

  • JdkHttpApiServer: Main server class, manages HTTP server lifecycle
  • ApplicationApiHandler: Handles /api/applications/* endpoints
  • PlatformApiHandler: Handles /api/platform/* endpoints
  • ApiAuthFilter: Optional authentication filter
  • ApplicationResponseDTO: JSON response model for applications
  • ErrorResponseDTO: JSON response model for errors

Dependencies

  • platform-java-api - Platform management API
  • jackson-databind - JSON serialization
  • slf4j-api - Logging
  • JDK 21+ (HttpServer is part of JDK)

Testing

Run tests with:

mvn test

Test coverage includes:

  • All HTTP endpoints (deploy, start, stop, undeploy, list, status)
  • Error handling and validation
  • Authentication filter
  • JSON serialization/deserialization

See Also