Expansion and Harvest API
This document describes the API endpoints used to manage and monitor the project's expand and harvest tasks. These tasks are initiated and monitored via a WebSocket connection, while related configuration and history can be retrieved through a REST endpoint.
Task Execution via WebSocket
To run an expand or harvest task, establish a WebSocket connection to the appropriate endpoint. The server will
immediately begin the task and stream plain-text log output over the connection. Once the task is complete, the server
will close the connection with a status code indicating success or failure.
Endpoints
- Expand Task:
ws://localhost:8080/tasks/expansion/expand - Harvest Task:
ws://localhost:8080/tasks/expansion/harvest
Behavior
- Connection: A client connects to one of the WebSocket endpoints.
- Execution & Logging: The server starts the corresponding task and begins streaming logs as plain-text messages.
- Termination: The server closes the connection when the task finishes.
Connection Close Codes
The WebSocket close code indicates the outcome of the task.
| Status Code | Reason | Description |
|---|---|---|
1000 | Normal Closure | The task completed successfully. |
1011 | Internal Server Error | The task failed due to an error. Review logs for details. |
Example Log Stream
Upon connection, you will receive a continuous stream of logs similar to the following:
C:\WINDOWS\System32\cmd.exe /C java net.democritus.runner.NsxPrimeRunner expand --expansionSettings C:\NSF\workspace\bookApp\conf\expansionSettings.xml --cleanRuntime
context:
net.democritus:nsx-prime 2024.0.1
net.democritus.metamodel:prime-core 2024.4.3
...
[INFO] Maven home: C:\ProgramData\chocolatey\lib\maven\apache-maven-3.9.10
[INFO] Maven local repository: C:\Users\koend\.m2\repository
--------------------------------------------------------
Cleaning expansion folder
----------------------------------------------------------------------------------------------------------------
Expansion
----------------------------------------------------------------------------------------------------------------
[INFO] Deleting C:\NSF\workspace\bookApp\expansions_old
--------------------------------------------------------
Expander version: 7.7.2
Expander build: 202408121549
Timestamp: Mon Jun 30 10:34:34 CEST 2025
BOOKAPP::1.0.0 (elements::JeeApplication)
--- initialize ----------------------
Executing tasks... (1/1)
--- expansion ----------------------
Executing tasks... (1815/1815)
...
--------------------------------------------------------
expansion ready after 2.422s
--------------------------------------------------------
Expansion complete
--------------------------------------------------------
Expansion Details via REST
This REST endpoint provides detailed information about the expansion configuration and the history of previous expansion runs.
GET /expansion
Retrieves the expansion settings and run history.
Request
Example Request:
curl http://localhost:8080/expansion
Success Response (200 OK)
The response is a JSON object containing the current settings derived from expansionSettings.xml and a list of all expansion tasks executed since the server started.
Response Body Structure
data(Object): The main container for the expansion data.properties(Object): Contains the core details of the expansion configuration.settings(Object): A JSON representation of theexpansionSettings.xmlfile. It includes details such as program expansions, resource dependencies, and local directory paths.programExpansions(Array): A list of programs to be expanded.expansionResources(Array): A list of dependencies required for the expansion.expansionDirectory(String): The path to the output directory for the expansion.modelDirectory(String): The path to the source model directory.
history(Array<Object>): A list of all expansion tasks that have been run, with the most recent first.id(String): A unique identifier for the historical run.type(String): The object type, typicallyexpansion-log.properties.startedAt(Float): The Unix timestamp (epoch time) when the task was started.links(Object): Links to retrieve more details about this specific run and its artifacts.
links(Object): Links for the resource itself.
Expansion Artifacts
The artifacts endpoints are currently not functional.
These will be fixed in a future release.
Example Response
Click to see the full example response
{
"data": {
"id": "expansion",
"type": "expansion",
"properties": {
"settings": {
"id": "expansionSettings.xml",
"type": "expansionControl::ExpansionSettings",
"format": "model",
"properties": {
"programExpansions": [
{
"id": "bookApp::1.0.0::bookApp",
"type": "expansionControl::ProgramExpansion",
"format": "model",
"properties": {
"variant": "bookApp",
"type": {
"id": "elements::JeeApplication",
"label": "JeeApplication",
"type": "expansionControl::ProgramType",
"format": "reference",
"links": {
"self": "/data/expansionControl%3A%3AProgramType/elements%3A%3AJeeApplication"
}
},
"target": "bookApp::1.0.0"
},
"meta": {
"origin": "file"
},
"links": {
"self": "/expansion/settings/expansionControl/ProgramExpansion/bookApp%3A%3A1.0.0%3A%3AbookApp"
}
}
],
"expansionResources": [
{
"id": "net.democritus.metamodel:prime-core::2024.4.3",
"label": "net.democritus.metamodel:prime-core",
"type": "expansionControl::ExpansionResource",
"format": "reference",
"links": {
"self": "/expansion/resource/net.democritus.metamodel/prime-core/expansionControl/ExpansionResource/net.democritus.metamodel%3Aprime-core%3A%3A2024.4.3"
}
}
],
"settingsDirectorys": [
{
"type": "expansionControl::SettingsDirectory",
"format": "model",
"properties": {
"directory": "C:\\NSF\\workspace\\bookApp\\settings"
},
"meta": {
"origin": "file"
}
}
],
"expansionDirectory": "C:\\NSF\\workspace\\bookApp\\expansions",
"modelDirectory": "C:\\NSF\\workspace\\bookApp"
},
"meta": {
"ns-model-server.resource.id": "expansionSettings",
"origin": "file"
}
},
"history": [
{
"id": "43e77f59-f0ef-491c-8886-8def5fb049cd",
"type": "expansion-log",
"format": "reference",
"properties": {
"startedAt": 1751272077.493263500
},
"links": {
"self": "/expansion/43e77f59-f0ef-491c-8886-8def5fb049cd",
"artifacts": "/expansion/43e77f59-f0ef-491c-8886-8def5fb049cd/artifacts"
}
},
{
"id": "28789baa-1571-4a2e-9914-7515355161f1",
"type": "expansion-log",
"format": "reference",
"properties": {
"startedAt": 1751272441.948276200
},
"links": {
"self": "/expansion/28789baa-1571-4a2e-9914-7515355161f1",
"artifacts": "/expansion/28789baa-1571-4a2e-9914-7515355161f1/artifacts"
}
}
]
},
"links": {
"self": "/expansion"
}
},
"server": {
"version": "1.10.1"
}
}