API Integration

Code To UML Gateway cung cấp các route tương thích Kroki và universal JSON API. Client gọi Gateway thay vì gọi trực tiếp Java core hoặc renderer companion.

1. Server và xác thực

Môi trường	Base URL
Local Gateway	http://localhost:8000
Production Gateway	https://kroki-render-vsf.duckdns.org

Các POST render và validation yêu cầu shared rendering token:

Authorization: Bearer {shared-rendering-token}

Token được cấu hình phía server bằng RENDER_API_KEYS. Các route GET cho Playground, catalog, health, metrics và encoded render là public.

2. Endpoint

Method	Path	Auth	Mục đích
GET	/	Public	API index
POST	/	Bearer	Render bằng Kroki JSON envelope
GET	/playground	Public	Playground web
GET	/healthz	Public	Dependency health của Gateway
GET	/health, /v1/health	Public	Health chi tiết của core
GET	/metrics	Public	Prometheus metrics
GET	/api/diagram-types	Public	Renderer và capability runtime
GET	/api/themes	Public	Universal theme catalog
POST	/api/validate-options	Bearer	Kiểm tra universal options
POST	/api/render	Bearer	Universal JSON render
POST	/{engine}/{format}	Bearer	Kroki-compatible render
GET	/{engine}/{format}/{encodedSource}	Public	Render source đã encode

3. Kroki-compatible POST

Gửi raw source tới engine và format đã chọn:

curl -X POST "$CODE_TO_UML_URL/plantuml/svg" \
  -H "Authorization: Bearer $CODE_TO_UML_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary $'@startuml\nAlice -> Bob\n@enduml'

Route này nhận text/plain, application/xml hoặc JSON có diagram_source và diagram_options. Option có thể nằm trong source directive, query hoặc header động kroki-diagram-options-{optionName}.

Gửi đầy đủ renderer, format và source trong một JSON envelope tới POST /:

{
  "diagram_source": "@startuml\nAlice -> Bob\n@enduml",
  "diagram_type": "plantuml",
  "output_format": "svg",
  "diagram_options": {
    "scale": 2
  }
}

4. Universal JSON API

POST /api/render kiểm tra option nghiêm ngặt và trả 400 khi option không xác định hoặc không hợp lệ.

POST /api/render
Content-Type: application/json
Authorization: Bearer {token}

{
  "diagramType": "mermaid",
  "format": "svg",
  "source": "flowchart LR\n  Cart --> Payment",
  "options": {
    "theme": "dark",
    "scale": 2
  }
}

Request cần một trong diagramType hoặc diagram_type và một trong source hoặc diagram_source. format có alias output_format và mặc định là svg. Khi cả hai alias cùng xuất hiện, field camelCase được ưu tiên.

5. Kiểm tra option và đọc catalog

Kiểm tra option mà không render:

POST /api/validate-options
Content-Type: application/json
Authorization: Bearer {token}

{
  "diagramType": "graphviz",
  "options": {
    "direction": "lr",
    "edge-routing": "orthogonal"
  }
}

Response có valid, renderer, resolvedOptions và warnings. Dùng endpoint này khi client cho phép nhập option động.

GET /api/diagram-types trả renderer, alias, format, phương thức được hỗ trợ, adapter và capability. GET /api/themes trả id, version và displayName của các universal theme. Đây là dữ liệu phù hợp để tạo selector tại runtime.

6. Encoded GET

Route public dùng cho diagram nhúng trong Markdown và GitLab:

GET /{engine}/{format}/{encodedSource}

encodedSource là UTF-8 source được zlib DEFLATE rồi Base64 URL-safe và khớp ^[A-Za-z0-9_-]+={0,2}$. Source có thể được giải mã từ URL, vì vậy route này không phù hợp với nội dung nhạy cảm.

Encoded GET hỗ trợ ETag, If-None-Match và có thể trả 304 Not Modified. Gateway áp dụng result cache và request coalescing cho route này.

Khi operator bật Pydia, encoded GET công khai cũng có thể yêu cầu thực thi Python source. Rendering deployment phải cô lập Pydia bằng sandbox, Unix socket, network policy và resource limits trước khi đăng ký renderer này. Client cần đọc runtime catalog thay vì mặc định coi Pydia luôn khả dụng.

7. Query, header và response

Input	Vị trí	Ý nghĩa
background	Query	Background export: white, black, transparent, #ffffff hoặc #000000
Accept	Header	MIME output mong muốn
X-Request-Id	Header	Correlation ID chuyển đến core
kroki-diagram-options-{optionName}	Header	Dynamic render option

Render thành công có thể trả SVG, PNG, JPEG, PDF hoặc plain text. Các header có thể gồm ETag, Cache-Control, X-Diagram-Pipeline, X-Diagram-Renderer, X-Diagram-Adapter và X-Diagram-Warnings. X-Cache chỉ áp dụng cho POST /{engine}/{format} và encoded GET.

8. Status code và lỗi

Status	Ý nghĩa
204	Render thành công nhưng không tạo response body
304	ETag của encoded GET vẫn còn hiệu lực
400	Request, source, format hoặc option không hợp lệ
401	Thiếu hoặc sai Bearer token
404	Renderer hoặc format không được hỗ trợ
413	Request body vượt giới hạn Gateway
429	Rate limit; thời gian chờ nằm trong Retry-After
502	Core không kết nối được hoặc response vượt giới hạn
503	Health endpoint báo unavailable
504	Core hoặc renderer vượt upstream timeout

Gateway thường trả lỗi JSON dạng {"error":"..."}. Core có thể trả object error với code, message, diagramCode và line, hoặc trả text, HTML hay hình ảnh tùy route và Accept. Client cần kiểm tra status code và Content-Type trước khi parse body.

Schema, example và response đầy đủ nằm trong docs/api-docs.yaml. Xem OpenAPI để mở, kiểm tra hoặc dùng contract với công cụ khác.