backend-infra-engineer: Release v0.3.3 snapshot
This commit is contained in:
scawful
309
src/cli/service/api/README.md
Normal file
309
src/cli/service/api/README.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# YAZE HTTP REST API
|
||||
|
||||
The YAZE HTTP REST API provides external access to YAZE functionality for automation, testing, and integration with external tools.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Building with HTTP API Support
|
||||
|
||||
The HTTP API is enabled automatically when building with AI-enabled presets:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
cmake --preset mac-ai
|
||||
cmake --build --preset mac-ai --target z3ed
|
||||
|
||||
# Linux
|
||||
cmake --preset lin-ai
|
||||
cmake --build --preset lin-ai --target z3ed
|
||||
|
||||
# Windows
|
||||
cmake --preset win-ai
|
||||
cmake --build --preset win-ai --target z3ed
|
||||
```
|
||||
|
||||
Or enable it explicitly with the CMake flag:
|
||||
|
||||
```bash
|
||||
cmake -B build -DYAZE_ENABLE_HTTP_API=ON
|
||||
cmake --build build --target z3ed
|
||||
```
|
||||
|
||||
### Running the HTTP Server
|
||||
|
||||
Start z3ed with the `--http-port` flag:
|
||||
|
||||
```bash
|
||||
# Start on default port 8080
|
||||
./build/bin/z3ed --http-port=8080
|
||||
|
||||
# Start on custom port with specific host
|
||||
./build/bin/z3ed --http-port=9000 --http-host=0.0.0.0
|
||||
|
||||
# Combine with other z3ed commands
|
||||
./build/bin/z3ed agent --rom=zelda3.sfc --http-port=8080
|
||||
```
|
||||
|
||||
**Security Note**: The server defaults to `localhost` for safety. Only bind to `0.0.0.0` if you understand the security implications.
|
||||
|
||||
## API Endpoints
|
||||
|
||||
All endpoints return JSON responses and support CORS headers.
|
||||
|
||||
### GET /api/v1/health
|
||||
|
||||
Health check endpoint for monitoring server status.
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/health
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "1.0",
|
||||
"service": "yaze-agent-api"
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes:**
|
||||
- `200 OK` - Server is healthy
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/models
|
||||
|
||||
List all available AI models from all registered providers (Ollama, Gemini, etc.).
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/models
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"models": [
|
||||
{
|
||||
"name": "qwen2.5-coder:7b",
|
||||
"provider": "ollama",
|
||||
"description": "Qwen 2.5 Coder 7B model",
|
||||
"family": "qwen2.5",
|
||||
"parameter_size": "7B",
|
||||
"quantization": "Q4_0",
|
||||
"size_bytes": 4661211616,
|
||||
"is_local": true
|
||||
},
|
||||
{
|
||||
"name": "gemini-1.5-pro",
|
||||
"provider": "gemini",
|
||||
"description": "Gemini 1.5 Pro",
|
||||
"family": "gemini-1.5",
|
||||
"parameter_size": "",
|
||||
"quantization": "",
|
||||
"size_bytes": 0,
|
||||
"is_local": false
|
||||
}
|
||||
],
|
||||
"count": 2
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes:**
|
||||
- `200 OK` - Models retrieved successfully
|
||||
- `500 Internal Server Error` - Failed to retrieve models (see `error` field)
|
||||
|
||||
**Response Fields:**
|
||||
- `name` (string) - Model identifier
|
||||
- `provider` (string) - Provider name ("ollama", "gemini", etc.)
|
||||
- `description` (string) - Human-readable description
|
||||
- `family` (string) - Model family/series
|
||||
- `parameter_size` (string) - Model size (e.g., "7B", "13B")
|
||||
- `quantization` (string) - Quantization method (e.g., "Q4_0", "Q8_0")
|
||||
- `size_bytes` (number) - Model size in bytes
|
||||
- `is_local` (boolean) - Whether model is hosted locally
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
All endpoints return standard HTTP status codes and JSON error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Detailed error message"
|
||||
}
|
||||
```
|
||||
|
||||
Common status codes:
|
||||
- `200 OK` - Request succeeded
|
||||
- `400 Bad Request` - Invalid request parameters
|
||||
- `404 Not Found` - Endpoint not found
|
||||
- `500 Internal Server Error` - Server-side error
|
||||
|
||||
## CORS Support
|
||||
|
||||
All endpoints include CORS headers to allow cross-origin requests:
|
||||
```
|
||||
Access-Control-Allow-Origin: *
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Architecture
|
||||
|
||||
The HTTP API is built using:
|
||||
- **cpp-httplib** - Header-only HTTP server library (`ext/httplib/`)
|
||||
- **nlohmann/json** - JSON serialization/deserialization
|
||||
- **ModelRegistry** - Unified model management across providers
|
||||
|
||||
### Code Structure
|
||||
|
||||
```
|
||||
src/cli/service/api/
|
||||
├── http_server.h # HttpServer class declaration
|
||||
├── http_server.cc # Server implementation and routing
|
||||
├── api_handlers.h # Endpoint handler declarations
|
||||
├── api_handlers.cc # Endpoint implementations
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Threading Model
|
||||
|
||||
The HTTP server runs in a background thread, allowing z3ed to continue normal operation. The server gracefully shuts down when z3ed exits.
|
||||
|
||||
### CMake Integration
|
||||
|
||||
Enable with:
|
||||
```cmake
|
||||
option(YAZE_ENABLE_HTTP_API "Enable HTTP REST API server" ${YAZE_ENABLE_AGENT_CLI})
|
||||
```
|
||||
|
||||
When enabled, adds compile definition:
|
||||
```cpp
|
||||
#ifdef YAZE_HTTP_API_ENABLED
|
||||
// HTTP API code
|
||||
#endif
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. Start the server:
|
||||
```bash
|
||||
./build/bin/z3ed --http-port=8080
|
||||
```
|
||||
|
||||
2. Test health endpoint:
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/health | jq
|
||||
```
|
||||
|
||||
3. Test models endpoint:
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/models | jq
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
Use the provided test script:
|
||||
```bash
|
||||
scripts/agents/test-http-api.sh 8080
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
The HTTP API can be tested in CI via workflow_dispatch:
|
||||
```bash
|
||||
gh workflow run ci.yml -f enable_http_api_tests=true
|
||||
```
|
||||
|
||||
See `docs/internal/agents/gh-actions-remote.md` for details.
|
||||
|
||||
## Future Endpoints (Planned)
|
||||
|
||||
The following endpoints are planned for future releases:
|
||||
|
||||
- `POST /api/v1/chat` - Send prompts to AI agent
|
||||
- `POST /api/v1/tool/{tool_name}` - Execute specific tools
|
||||
- `GET /api/v1/rom/status` - ROM loading status
|
||||
- `GET /api/v1/rom/info` - ROM metadata
|
||||
|
||||
See `docs/internal/AI_API_ENHANCEMENT_HANDOFF.md` for the full roadmap.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Localhost Only**: Default host is `localhost` to prevent external access
|
||||
- **No Authentication**: Currently no authentication mechanism (planned for future)
|
||||
- **CORS Enabled**: Cross-origin requests allowed (may be restricted in future)
|
||||
- **Rate Limiting**: Not implemented (planned for future)
|
||||
|
||||
For production use, consider:
|
||||
1. Running behind a reverse proxy (nginx, Apache)
|
||||
2. Adding authentication middleware
|
||||
3. Implementing rate limiting
|
||||
4. Restricting CORS origins
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Port already in use"
|
||||
|
||||
If you see `Failed to listen on port`, another process is using that port:
|
||||
|
||||
```bash
|
||||
# Find the process
|
||||
lsof -i :8080
|
||||
|
||||
# Use a different port
|
||||
./build/bin/z3ed --http-port=9000
|
||||
```
|
||||
|
||||
### "Failed to start HTTP API server"
|
||||
|
||||
Check that:
|
||||
1. The binary was built with `YAZE_ENABLE_HTTP_API=ON`
|
||||
2. The port number is valid (1-65535)
|
||||
3. You have permission to bind to the port (<1024 requires root)
|
||||
|
||||
### Server not responding
|
||||
|
||||
Verify the server is running and reachable:
|
||||
```bash
|
||||
# Check if server is listening
|
||||
netstat -an | grep 8080
|
||||
|
||||
# Test with verbose curl
|
||||
curl -v http://localhost:8080/api/v1/health
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new endpoints:
|
||||
|
||||
1. Declare handler in `api_handlers.h`
|
||||
2. Implement handler in `api_handlers.cc`
|
||||
3. Register route in `http_server.cc::RegisterRoutes()`
|
||||
4. Document endpoint in this README
|
||||
5. Add tests in `scripts/agents/test-http-api.sh`
|
||||
|
||||
Follow the existing handler pattern:
|
||||
```cpp
|
||||
void HandleYourEndpoint(const httplib::Request& req, httplib::Response& res) {
|
||||
// Set CORS header
|
||||
res.set_header("Access-Control-Allow-Origin", "*");
|
||||
|
||||
// Build JSON response
|
||||
json response;
|
||||
response["field"] = "value";
|
||||
|
||||
// Return JSON
|
||||
res.set_content(response.dump(), "application/json");
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Part of the YAZE project. See LICENSE for details.
|
||||
Reference in New Issue
Block a user