PolyAPI is a polyglot API architecture that demonstrates how to build production-ready APIs using multiple programming languages, each contributing isolated, well-defined modules. The system is orchestrated by a Python FastAPI gateway, and all inter-module communication happens exclusively via a JSON contract.
Different programming languages excel at different tasks. PolyAPI embraces this philosophy by allowing each module to be written in the language best suited for its purpose:
- Go (Sort Module): Chosen for its performance, simplicity, and excellent standard library for building lightweight microservices
Python was chosen as the gateway language for several important reasons:
-
Accessibility: Python's readable, English-like syntax lowers the barrier to entry for contributors. Developers can quickly understand and modify the gateway code regardless of their primary programming language.
-
Ecosystem: FastAPI provides excellent web framework capabilities with automatic OpenAPI documentation, native async support, and seamless Pydantic integration for request/response validation.
-
Learning Curve: New contributors can focus on learning the module-specific logic rather than struggling with complex gateway code.
-
Community: Python is one of the most popular languages in the world, making it easy to find contributors who can work on the orchestration layer.
┌─────────────────────────────────────────────────────────────┐
│ Client │
└─────────────────────┬───────────────────────────────────────┘
│ HTTP + JSON
▼
┌─────────────────────────────────────────────────────────────┐
│ PolyAPI Gateway (Python) │
│ :8000 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ /health │ │ /modules │ │ /sort (proxy) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
│ HTTP + JSON Contract
▼
┌─────────────────────────────────────────────────────────────┐
│ Sort Module (Go) :8081 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ /health │ │ /sort │ | future-modules │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
# Clone and navigate to the project
git clone https://github.com/yourusername/polyapi.git
cd polyapi
# Start all services
make up
# Test the API
curl -X POST http://localhost:8000/sort \
-H "Content-Type: application/json" \
-d '{"payload": {"items": ["zebra", "ant", "mango"], "order": "asc"}}'
# Expected response:
# {
# "request_id": "...",
# "module": "sort",
# "version": "1.0.0",
# "status": "success",
# "data": {
# "sorted": ["ant", "mango", "zebra"],
# "item_type": "string",
# "count": 3
# },
# "error": null
# }
# View logs
make logs
# Stop services
make down| Service | Language | Port | Description |
|---|---|---|---|
| gateway | Python | 8000 | FastAPI orchestration layer |
| sort | Go | 8081 | String and number sorting service |
PolyAPI is designed to be easily extensible. To add a new module:
- Create a new directory under
modules/ - Implement your service in any language
- Follow the JSON contract standard (see
docs/CONTRACT.md) - Register the module in
gateway/config.py - Update documentation
See docs/CONTRIBUTING.md for detailed instructions.
| Method | Path | Description |
|---|---|---|
| GET | /health |
Gateway health check |
| GET | /modules |
List all registered modules |
| POST | /sort |
Proxy to Go sort module |
| Module | Method | Path | Description |
|---|---|---|---|
| sort | GET | /health |
Module health check |
| sort | POST | /sort |
Sort items (strings or numbers) |
# Run linting
make lint
# Run tests
make test
# Clean up
make clean- Architecture: System design and philosophy
- Contract Specification: JSON contract format and error codes
- Contributing Guide: How to add new modules
- Sort Module: Sort module reference
- Contributor License Agreement: Terms for contributing
MIT License. see LICENSE for details.