A simple API server that converts Draw.io diagram files to SVG format.
Note: This application is currently in beta release. While core functionality is operational, certain features remain under active development. The system may experience intermittent stability issues, particularly when processing malformed
.drawio
files.
Network Documentation Automation. Primarily created to generate dynamic network diagrams from Netbox data, it's used by the Netbox Ninja Plugin to automatically create and update network documentation. Perhaps it can be useful in some other context too.
This service provides a REST API endpoint that accepts Draw.io (.drawio) files and returns them converted to SVG format. It can be used for automated documentation workflows or with systems that needs to render Draw.io diagrams as SVGs.
In practice, the implementation brings together the following components:
- drawio-export Docker image
- Minimal FastAPI server
- Nginx for HTTPs
- Convert Draw.io files to SVG format
- RESTful API interface
- Docker-based deployment
- Authentication support
- Headless Draw.io desktop for reliable conversions
- Docker and Docker Compose
- Make (optional, for using Makefile commands)
-
Clone the repository:
git clone https://github.com/rautanen-companies/drawio-export-api.git cd drawio-export-api
-
Build and start the service (without TLS):
make up
Alternatively start the service with TLS enabled:
make prod-up
Send a POST request to /convert
with:
- The .drawio file in the request body
- Authorization header with your API token
Example using curl:
curl -X POST \
-H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/octet-stream" \
--data-binary @your-diagram.drawio \
http://localhost:8000/convert > output.svg
Token can be set in dev.env
and prod.env
files.
The project includes a simple Python client that makes it possible to interact with the API. You can use it like this:
python src/drawio_export_api_client/client.py \
http://localhost:8000/svg \
your-token-here \
path/to/your/diagram.drawio
For HTTPS endpoints, you'll need to provide a certificate path:
python src/drawio_export_api_client/client.py \
https://localhost:443/svg \
your-token-here \
path/to/your/diagram.drawio
path/to/certificate.pem
The client provides:
- Simple interface for API interaction
- Built-in error handling
- HTTPS support with certificate verification
- Command-line and programmatic usage options
The API returns:
- 200 OK with the SVG content on successful conversion
- 400 Bad Request if the input file is invalid
- 401 Unauthorized if the authentication token is missing or invalid
- 500 Internal Server Error if the conversion fails
-
Single Page Export
- Currently only exports the first page (Page-1) of multi-page diagrams
- No support for selecting specific pages to export
-
Format Support
- Only supports SVG export format
- No support for PNG, PDF, or other export formats
- No control over SVG export options (like scale, background color)
-
Error Handling
- Limited error messages for malformed Draw.io files
- No detailed feedback on conversion failures
-
Performance
- Single-threaded processing
- No request queuing for high-load scenarios
- Each conversion starts a new Draw.io instance
-
Enhanced Export Options
- Support for multiple page export
- Additional export formats (PNG, PDF)
-
Performance Improvements
- Request queuing system
-
Enhanced Security
- Rate limiting
- API key management interface
-
Monitoring and Logging
- Health check endpoint
- Detailed error logging
For development setup and guidelines, please refer to our Contributing Guidelines.
Configuration is done through environment variables:
AUTH_TOKEN
: API authentication tokenPORT
: Server port (default: 8000)- Additional configuration can be set in
docker-compose.override.yml
This project is licensed under the MIT License - see the LICENSE file for details.
Please do not commit any sensitive information such as API tokens. Use environment variables for sensitive data.
This project builds on top of drawio-export. Thanks goes to https://github.com/rlespinasse!