Repository navigation
OpenAPI
OpenAPI is a specification for building APIs that allows both humans and computers to understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.
OpenAPI (formerly known as Swagger) is a language-agnostic interface description for HTTP APIs that allows both humans and computers to understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.
In AEGIS, OpenAPI plays a crucial role in providing standardized interfaces for interacting with both the consciousness engine and the AGI framework. The system exposes RESTful endpoints that follow OpenAPI specifications, making it easier for developers to integrate with AEGIS components.
- Standardization: Consistent API design across all AEGIS components
- Documentation: Automatically generated, interactive API documentation
- Tooling: Support for code generation, testing, and validation
- Interoperability: Easy integration with external systems and tools
The main API server provides access to both consciousness and AGI functionalities:
-
GET /api/consciousness- Real-time consciousness metrics -
GET /api/agi- AGI system status and capabilities -
POST /api/input- Send sensory input to consciousness system -
POST /api/chat- Send chat message to AGI system -
GET /api/health- System health check -
WebSocket /ws- Real-time state streaming
Dedicated WebSocket server for secure cross-system messaging between consciousness and AGI systems.
Interactive API documentation is available at:
- http://localhost:8003/docs - Main API documentation
- http://localhost:8005/docs - Unified API documentation
These documentation interfaces are automatically generated from the OpenAPI specifications and provide:
- Interactive endpoint testing
- Request/response examples
- Schema definitions
- Authentication information
To access the AEGIS API, you can use any HTTP client. Here's a simple example using curl:
# Get consciousness state
curl http://localhost:8003/api/consciousness
# Send chat message
curl -X POST http://localhost:8003/api/chat \
-H "Content-Type: application/json" \
-d '{"message": "Hello AEGIS!", "session_id": "session123"}'For real-time updates, connect to the WebSocket endpoint:
const ws = new WebSocket('ws://localhost:8006/ws');
ws.onopen = function(event) {
console.log('Connected to AEGIS WebSocket');
};
ws.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('Received:', data);
};Machine-readable OpenAPI specifications are available at:
These JSON files can be used with OpenAPI tools for:
- Client code generation
- API testing
- Documentation generation
- Validation
When using the AEGIS OpenAPI interfaces, consider the following security aspects:
- Authentication: In production environments, API endpoints may require authentication tokens
- Encryption: All communication should be encrypted using HTTPS/TLS
- Rate Limiting: Be aware of rate limits to prevent overwhelming the system
- Input Validation: Always validate input data to prevent injection attacks
AEGIS's OpenAPI specification can be used with various tools:
Generate client libraries in various programming languages:
# Using openapi-generator
openapi-generator generate -i http://localhost:8003/openapi.json -g python -o ./clientImport the specification into testing tools like Postman or Insomnia for automated testing.
Use tools like ReDoc or Swagger UI to generate standalone documentation.
When working with AEGIS's OpenAPI:
- Always check the health endpoint first to ensure the system is running
- Handle errors gracefully by checking HTTP status codes
- Use appropriate headers for content type and authentication
- Implement retry logic for transient failures
- Monitor rate limits to avoid being throttled
For developers looking to extend AEGIS functionality:
- Follow the existing OpenAPI specification patterns
- Maintain consistent naming conventions
- Provide comprehensive documentation for new endpoints
- Implement proper error handling and status codes
- Ensure backward compatibility when possible
Common issues and solutions:
- Connection Refused: Ensure AEGIS is running and the correct port is being used
- 404 Not Found: Check that the endpoint URL is correct
- 400 Bad Request: Validate that request parameters and body are correctly formatted
- 500 Internal Server Error: Check system logs for detailed error information
For more detailed information about AEGIS's API implementation, see the API Integration documentation.