Skip to content

Commit f105cb4

Browse files
Flossyclaude
Flossy
and
claude
committed
Add comprehensive documentation for REST API and Web Console modules
- Created jplatform-rest-api/README.md with complete API documentation - All endpoints documented (deploy, start, stop, undeploy, list, status) - Request/response examples for each endpoint - Authentication configuration - Error response format - Component descriptions - Created jplatform-web-console/README.md with complete UI documentation - User interface sections (platform info, app management, metrics charts) - Usage instructions and deployment workflow - Browser compatibility requirements - Configuration options (port, refresh rates, chart customization) - Security considerations - Architecture overview - Updated main README.md to include jplatform-swing-ui in project structure All three UI modules now have comprehensive documentation: - REST API: Full HTTP API reference - Web Console: Browser-based UI guide - Swing UI: Desktop application guide Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 582b0ee commit f105cb4

3 files changed

Lines changed: 539 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ jplatform/
122122
├── jplatform-fs-watcher/ # Filesystem monitoring for auto-deployment ✅ **COMPLETE**
123123
├── jplatform-rest-api/ # HTTP REST API server ✅ **COMPLETE**
124124
├── jplatform-web-console/ # Browser-based management UI ✅ **COMPLETE**
125+
├── jplatform-swing-ui/ # Swing desktop management UI ✅ **NEW**
125126
├── jplatform-metrics-jmx/ # JMX metrics exporter ✅ **COMPLETE**
126127
├── jplatform-metrics-prometheus/ # Prometheus metrics exporter ✅ **COMPLETE**
127128
├── jplatform-storage/ # Persistent volume management ✅ **COMPLETE (2.0)**
@@ -574,6 +575,7 @@ Applications SHOULD use the provided `ManagedThreadPool`. Direct thread creation
574575
- Filesystem watcher (`jplatform-fs-watcher`) - auto-deployment with debouncing
575576
- REST API server (`jplatform-rest-api`) - full HTTP API
576577
- Web console (`jplatform-web-console`) - modern browser-based UI
578+
- Swing desktop UI (`jplatform-swing-ui`) - native desktop management interface ✅ **NEW in 1.1**
577579
578580
**Metrics & Monitoring (NEW in 1.0):**
579581
- JMX metrics exporter (`jplatform-metrics-jmx`) - JConsole/VisualVM integration

‎jplatform-rest-api/README.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# JPlatform REST API
2+
3+
HTTP REST API server for JPlatform management using JDK's built-in `com.sun.net.httpserver`.
4+
5+
## Overview
6+
7+
The `jplatform-rest-api` module provides a complete HTTP REST API for managing JPlatform instances. It offers programmatic access to deployment, lifecycle management, and metrics retrieval.
8+
9+
## Features
10+
11+
- **Full CRUD Operations**: Deploy, list, start, stop, undeploy applications
12+
- **Metrics Retrieval**: Get real-time resource usage (CPU, memory, threads)
13+
- **Status Monitoring**: Query application states and health
14+
- **JSON API**: Request and response bodies use JSON format
15+
- **Lightweight**: Uses JDK's built-in HTTP server (no external dependencies)
16+
- **Authentication**: Optional API key authentication via `ApiAuthFilter`
17+
18+
## API Endpoints
19+
20+
### Application Management
21+
22+
| Method | Endpoint | Description |
23+
|--------|----------|-------------|
24+
| POST | `/api/applications` | Deploy a new application |
25+
| GET | `/api/applications` | List all applications |
26+
| GET | `/api/applications/{id}` | Get application details |
27+
| GET | `/api/applications/{id}/status` | Get application status and metrics |
28+
| POST | `/api/applications/{id}/start` | Start an application |
29+
| POST | `/api/applications/{id}/stop` | Stop an application |
30+
| DELETE | `/api/applications/{id}` | Undeploy an application |
31+
| GET | `/api/applications/{id}/metrics` | Get resource metrics history |
32+
33+
### Platform Management
34+
35+
| Method | Endpoint | Description |
36+
|--------|----------|-------------|
37+
| GET | `/api/platform/status` | Get platform status and summary |
38+
| GET | `/api/platform/health` | Health check endpoint |
39+
40+
## Usage
41+
42+
### Starting the API Server
43+
44+
```java
45+
import org.flossware.jplatform.api.PlatformManager;
46+
import org.flossware.jplatform.core.ApplicationManager;
47+
import org.flossware.jplatform.rest.JdkHttpApiServer;
48+
49+
public class Main {
50+
public static void main(String[] args) throws IOException {
51+
PlatformManager manager = new ApplicationManager();
52+
JdkHttpApiServer server = new JdkHttpApiServer(manager, 8080);
53+
server.start();
54+
55+
System.out.println("API server running on http://localhost:8080");
56+
}
57+
}
58+
```
59+
60+
### Deploy Application
61+
62+
```bash
63+
curl -X POST http://localhost:8080/api/applications \
64+
-H "Content-Type: application/json" \
65+
-d '{
66+
"applicationId": "my-app",
67+
"name": "My Application",
68+
"mainClass": "com.example.MyApp",
69+
"classpathEntries": ["file:///path/to/app.jar"],
70+
"threadPool": {
71+
"corePoolSize": 4,
72+
"maxPoolSize": 20
73+
}
74+
}'
75+
```
76+
77+
**Response** (201 Created):
78+
```json
79+
{
80+
"applicationId": "my-app",
81+
"name": "My Application",
82+
"mainClass": "com.example.MyApp",
83+
"state": "DEPLOYED",
84+
"deployedAt": "2024-05-24T10:30:00Z",
85+
"metrics": {
86+
"cpuTimeNanos": 0,
87+
"heapUsedBytes": 0,
88+
"threadCount": 0
89+
}
90+
}
91+
```
92+
93+
### List Applications
94+
95+
```bash
96+
curl http://localhost:8080/api/applications
97+
```
98+
99+
**Response** (200 OK):
100+
```json
101+
[
102+
{
103+
"applicationId": "my-app",
104+
"name": "My Application",
105+
"mainClass": "com.example.MyApp",
106+
"state": "DEPLOYED",
107+
"deployedAt": "2024-05-24T10:30:00Z",
108+
"metrics": { ... }
109+
}
110+
]
111+
```
112+
113+
### Start Application
114+
115+
```bash
116+
curl -X POST http://localhost:8080/api/applications/my-app/start
117+
```
118+
119+
**Response** (200 OK):
120+
```json
121+
{
122+
"applicationId": "my-app",
123+
"state": "RUNNING",
124+
...
125+
}
126+
```
127+
128+
### Get Application Status
129+
130+
```bash
131+
curl http://localhost:8080/api/applications/my-app/status
132+
```
133+
134+
**Response** (200 OK):
135+
```json
136+
{
137+
"applicationId": "my-app",
138+
"state": "RUNNING",
139+
"deployedAt": "2024-05-24T10:30:00Z",
140+
"metrics": {
141+
"cpuTimeNanos": 1234567890,
142+
"heapUsedBytes": 52428800,
143+
"threadCount": 15
144+
}
145+
}
146+
```
147+
148+
### Stop Application
149+
150+
```bash
151+
curl -X POST http://localhost:8080/api/applications/my-app/stop
152+
```
153+
154+
**Response** (200 OK)
155+
156+
### Undeploy Application
157+
158+
```bash
159+
curl -X DELETE http://localhost:8080/api/applications/my-app
160+
```
161+
162+
**Response** (204 No Content)
163+
164+
### Get Platform Status
165+
166+
```bash
167+
curl http://localhost:8080/api/platform/status
168+
```
169+
170+
**Response** (200 OK):
171+
```json
172+
{
173+
"totalApplications": 3,
174+
"runningApplications": 2,
175+
"stoppedApplications": 1,
176+
"failedApplications": 0,
177+
"uptime": "2h 15m 30s"
178+
}
179+
```
180+
181+
## Error Responses
182+
183+
All errors return a consistent JSON structure:
184+
185+
```json
186+
{
187+
"error": "Application not found",
188+
"status": 404,
189+
"timestamp": "2024-05-24T10:30:00Z"
190+
}
191+
```
192+
193+
Common status codes:
194+
- `400` - Bad Request (invalid JSON, missing required fields)
195+
- `404` - Not Found (application does not exist)
196+
- `409` - Conflict (application already exists, invalid state transition)
197+
- `500` - Internal Server Error
198+
199+
## Authentication
200+
201+
Enable API key authentication:
202+
203+
```java
204+
JdkHttpApiServer server = new JdkHttpApiServer(manager, 8080);
205+
server.setApiKey("your-secret-api-key");
206+
server.start();
207+
```
208+
209+
Clients must include the API key in the `X-API-Key` header:
210+
211+
```bash
212+
curl -H "X-API-Key: your-secret-api-key" \
213+
http://localhost:8080/api/applications
214+
```
215+
216+
## Configuration
217+
218+
### Port
219+
220+
Default port is 8080. Override in constructor:
221+
222+
```java
223+
JdkHttpApiServer server = new JdkHttpApiServer(manager, 9090);
224+
```
225+
226+
### CORS
227+
228+
CORS is enabled by default for all origins. To restrict:
229+
230+
```java
231+
// Custom CORS configuration requires modifying ApiAuthFilter
232+
```
233+
234+
## Components
235+
236+
- **JdkHttpApiServer**: Main server class, manages HTTP server lifecycle
237+
- **ApplicationApiHandler**: Handles `/api/applications/*` endpoints
238+
- **PlatformApiHandler**: Handles `/api/platform/*` endpoints
239+
- **ApiAuthFilter**: Optional authentication filter
240+
- **ApplicationResponseDTO**: JSON response model for applications
241+
- **ErrorResponseDTO**: JSON response model for errors
242+
243+
## Dependencies
244+
245+
- `jplatform-api` - Platform management API
246+
- `jackson-databind` - JSON serialization
247+
- `slf4j-api` - Logging
248+
- JDK 21+ (HttpServer is part of JDK)
249+
250+
## Testing
251+
252+
Run tests with:
253+
254+
```bash
255+
mvn test
256+
```
257+
258+
Test coverage includes:
259+
- All HTTP endpoints (deploy, start, stop, undeploy, list, status)
260+
- Error handling and validation
261+
- Authentication filter
262+
- JSON serialization/deserialization
263+
264+
## See Also
265+
266+
- [Web Console](../jplatform-web-console/README.md) - Browser-based UI built on this API
267+
- [Swing UI](../jplatform-swing-ui/README.md) - Desktop UI using this API
268+
- [QUICKSTART](../QUICKSTART.md) - Quick start guide with API examples
269+
- [Main README](../README.md) - Platform overview

0 commit comments

Comments
 (0)