HTTP API

The same engine that powers the page is available over HTTP, so you can lay out maps from scripts, notebooks or a CI job. Two styles are offered: a synchronous endpoint that returns the finished files in one request, and an asynchronous job API with live progress. All responses are UTF-8; errors are JSON objects with an error field.

Quick start

Lay out a map and receive a ZIP with the laid-out SBGN-ML, the SVG drawing and a JSON report:

curl -sS -F "[email protected]" https://sbgn-layout.org/api/layout -o glycolysis_layout.zip

Ask for JSON instead (inline SVG and SBGN-ML strings plus the report):

curl -sS -H "Accept: application/json" -F "[email protected]" https://sbgn-layout.org/api/layout | jq '.report.timings'

Through the public URL a request is cut off after about 100 seconds (HTTP 524), queue time included. For large maps use the asynchronous jobs below, which have no such limit.

Options are form fields or query parameters, e.g. stop a process-description map before edge routing and skip the process stars:

curl -sS -F "[email protected]" "https://sbgn-layout.org/api/layout?steps=5&stars=0" -o map_layout.zip

Asynchronous jobs

For large maps, or when you want progress, create a job and follow it. Results are kept on the server for about two hours. A job belongs to whoever created it: the first request receives a cookie (sbgn_owner), and only requests carrying that cookie can see, download or delete the job. Everyone else gets 404, as for an unknown id. Keep the cookie in a cookie jar (-c / -b in curl):

# 1. create the job (HTTP 202); the cookie jar keeps your owner cookie
JOB=$(curl -sS -c jar.txt -b jar.txt -F "[email protected]" -F "perStep=1" -F "original=1" https://sbgn-layout.org/api/jobs | jq -r .id)

# 2. follow progress as Server-Sent Events (one JSON object per "data:" line)
curl -sS -N -b jar.txt https://sbgn-layout.org/api/jobs/$JOB/events

# 3. fetch the result and the files
curl -sS -b jar.txt https://sbgn-layout.org/api/jobs/$JOB | jq '.report.conflicts'
curl -sS -b jar.txt -o result.svg  https://sbgn-layout.org/api/jobs/$JOB/files/map_layout.svg
curl -sS -b jar.txt -o result.sbgn https://sbgn-layout.org/api/jobs/$JOB/files/map_layout.sbgn
curl -sS -b jar.txt -o all.zip     https://sbgn-layout.org/api/jobs/$JOB/files/all.zip

Event types on the stream: status (queued · running · done · error, with queuePosition), language, graph (node/edge counts), step (index, name, running/done, ms, constraints added), log, done, error. The stream replays the history first, so connecting late is fine.

Open one of your finished jobs with /?job=<id>; the link works only in the browser that started the job.

With perStep=1 every step writes a snapshot. The snapshot for step 1 of a process-description map is the skeleton graph the step builds, not the input again; its file is also listed as outputs.skeletonSvg. It shows the skeleton after the unconstrained force-directed pass that opens step 2 (with skeletonShape=fd the angles of its edges decide the alignments), so the file is written after step 2 but keeps step index 1. With steps=1 or skeletonShape=topology that pass does not run and the snapshot shows the input positions; graphLayout in the report's first step says which (fd or input).

Endpoints

Options

Output files and report

• <name>_layout.sbgn — the laid-out map as SBGN-ML 0.3 (positions, ports, arc bend points).
• <name>_layout.svg — the drawing with a viewBox around the map plus a 40 px border. _layout.png when requested.
• <name>_original.svg, <name>_stepN.svg — snapshots when requested; for a process-description map step 1 is <name>_skeleton.svg.
• <name>_result.json — the report: language, graph counts, steps (name, description, ms, constraintsAdded, skipped), constraints (total, horizontal, vertical, separation), conflicts (dropped or unsatisfied constraints with phase, reason and node labels), timings, bounds, warnings.

The pipeline

Process description maps run through six steps; every step adds constraints and re-solves the layout with the constrained force-directed solver (cola).

1. Skeleton. Removes docking and compartments, reroutes tags, remembers complexes and builds the skeleton graph (processes and their structural neighbours).
2. Skeleton Constraints. Runs an unconstrained force-directed pass on the skeleton (not with skeletonShape=topology), chooses one shortest metabolic cycle per biconnected block (Tarjan), embeds each as a rectangle, and aligns the remaining skeleton edges along their dominant axis.
3. Individual Constraints. Determines the substrate/product axis of every process and adds the separation constraints for its left- and right-hand side.
4. Process Stars. Places the leaves of a process on a symmetric star: main substrate and product on the axis, cofactors on mirrored diagonals, the enzyme on the free perpendicular side.
5. Stubs. Adds stub constraints for catalyses and stimulations on a free side of the process, then runs the hierarchical compartment layout.
6. Edge Routing. Restores complexes and tags, routes the edges orthogonally with Adaptagrams (libavoid) and re-inserts the compartments around their members.

Entity relationship maps run through four steps. The arc is the unit there: an arc keeps its outcomes and ports on one straight line, and every arc attached to them leaves at a right angle.

1. Force-Directed. Prepares the graph (docking, compartments, tags) and takes the hyperedge nodes (outcomes, ports) out, so every arc between two glyphs becomes one edge; one force-directed pass over the glyphs.
2. Skeleton Constraints. Gives every arc between two glyphs the axis of its force-directed angle: both glyphs on one line, in order, with room for the arc's nodes.
3. Hyperedge Nodes. Puts the outcomes and ports back in line with their arc's ends; every other arc there (influences, logic arcs) leaves perpendicular.
4. Edge Routing. Restores tags, routes the edges with Adaptagrams, re-inserts compartments and ends arcs on pins at the glyph borders.

Activity flow maps run through seven steps that build a hierarchy instead of process templates.

1. LO Trees. Prepares the graph; every tree of logical operators, with the inputs that feed only it, is laid out on its own and stands in as one placeholder box.
2. Feedback Arc Set. Removes a minimal, stable feedback arc set so the influences form a DAG. Nothing moves in this step.
3. Skeleton. Aligns a longest path of the DAG top to bottom in one column per component.
4. Levels. Adds the nodes joined to the previous level, sources above and targets below their anchor.
5. Insert LO Trees. Replaces the placeholders by their trees, turned towards their output, and takes the feedback arcs back in.
6. LO Stubs. Puts an operator's inputs on its input side and its output on the other; final constrained force-directed run.
7. Edge Routing. Restores tags, routes the edges with Adaptagrams and re-inserts compartments.

Constraints that contradict each other (e.g. separations and alignments closing a cycle) are detected by a feasibility guard before the solver runs; automatically generated ones are dropped and listed as conflicts in the report, so a dropped constraint never silently distorts the result.

Python example

import requests, time

s = requests.Session()  # keeps the owner cookie, so the job stays visible to you
with open("map.sbgn", "rb") as f:
    job = s.post("https://sbgn-layout.org/api/jobs", files={"file": f}, data={"perStep": "1"}).json()

while True:
    r = s.get(f"https://sbgn-layout.org/api/jobs/{job['id']}").json()
    if r["status"] in ("done", "error"):
        break
    time.sleep(1)

if r["status"] == "done":
    open("map_layout.svg", "w").write(r["svg"])
    open("map_layout.sbgn", "w").write(r["sbgn"])
    print("conflicts:", len(r["report"]["conflicts"]), "layout ms:", r["report"]["timings"]["layoutMs"])
else:
    print("failed:", r["error"])

Limits and configuration

• Uploads up to 40 MB (MAX_UPLOAD_BYTES). One layout runs per Java process; by default as many run in parallel as the server has CPUs minus two (MAX_PARALLEL_JOBS), further requests queue. The queue takes turns between users, so one person's batch does not hold up everyone else; each user may have 5 jobs queued or running (MAX_ACTIVE_JOBS_PER_USER, HTTP 429 beyond), and when 100 jobs are waiting in total (MAX_QUEUED_JOBS) new ones get HTTP 503 with Retry-After.
• A run is aborted after 10 minutes (RUNNER_TIMEOUT_MS). Maps with more than ~1000 nodes spend most of that in the edge-routing step; to skip routing, stop one step earlier (steps=5 for PD).
• Results are deleted after 2 hours (JOB_TTL_MS). The server picks a 64-bit JVM from JAVA_BIN, JAVA_HOME, /usr/libexec/java_home (macOS) or PATH; Java 8 or newer (64-bit).
• Maps are processed on this server only and never shared; other users cannot list or open your jobs. The ER/AF SBGN-ML writers cover the common constructs; if an export fails, the SVG is still delivered and the reason is listed under warnings.