OpenAPI Document
The App Manager API is documented in a JSON file conforming to the OpenAPI 3.0 specification.
Swagger
The best way to visualize and interact with the API is through Swagger.
Swagger Editor
With Swagger Editor, you can edit the OpenAPI document inside your browser, while previewing the documentation in real time.
Swagger Editor can be installed locally with https://github.com/swagger-api/swagger-editor, or by cloning the repository.
git clone https://github.com/swagger-api/swagger-editor.git
Then open index.html and import openapi.json.
You can then make edits to the OpenAPI document in the left panel (in YAML format) and visualize the UI in the right panel.
Swagger UI
If you do not need to edit the OpenAPI document, you can simply use Swagger UI.
The tool https://github.com/vajahath/open-swagger-ui will allow you to open a local openapi.json file in the Swagger UI.
It requires Node >=10 and can be installed via npm:
Then, change to the directory containing openapi.json and run:
open-swagger-ui .\openapi.json --open
Authentication
In order to use the API, you will need to provide an authorization token.
When making an API call, use -H 'Authorization: Token 123abc', replacing 123abc with your token.
If you are using Swagger UI, click on the ‘Authorize’ button and use value Token 123abc, replacing 123abc with your token.
You can generate an authentication token from your username and password with a POST /accounts/api-token-auth/ call, with the following request body:
{
"username": "user123",
"password": "pw123"
}
If you fail to authenticate, any API calls (except for /accounts/api-token-auth/) will return an error code 401.
Error Codes
The API uses conventional HTTP response codes to indicate the success or failure of an API request.
Response
All API calls will generate a response in the format below:
{
"requestId": null,
"result": "",
"error": null
}
requestId contains a unique identifier for each request. You can view the contents of a specific request with GET /api/request/{requestId}/ .
result contains the result of the request.
error contains an error code and description if the request failed on the backend. (Note: The API call, itself, will still be successful and return code 200).
Endpoints
All API endpoints are listed below, along with a brief description for each. More detail on usage and expected results can be found in the OpenAPI document or viewed through the Swagger UI.
Account management (accounts)
General high-level API calls (api)
GET /api/folder/{folderId}/tree/ Return a tree containing all children of the specified folder
GET /api/request/{requestId}/ Return the contents of the specified request
GET /api/status/ Report the status of the API backend, including mode
GET /api/tree/ Return the highest level tree for this install
GET /api/{entity}/allconfig/ Return a full listing of an entity type (nodes, apps, objects)
GET /api/{schemaId}/schema/ Return the schema file for the specified schema ID
Operations on a specified node (api_node)
GET /api/{nodeId}/apps/ Return a list of all apps under the specified node
POST /api/{nodeId}/command/ Send a command to the specified node
GET /api/{nodeId}/config/ Return the settings for the specified node
POST /api/{nodeId}/config/ Adjust the settings for the specified node
POST /api/{nodeId}/delete/ Delete the specified node from the remote manager database
GET /api/{nodeId}/export/ Full recursive export for the specified node
POST /api/{nodeId}/import/ Full recursive import for the specified node
POST /api/{nodeId}/sync/ Sync the specified node to the remote manager
GET /api/{nodeId}/tree/ Return the highest level tree for the specified node
GET /api/{nodeId}/view/ Return the schema and settings for the specified node
Operations on a specified app (api_app)
POST /api/{nodeId}/{appId}/command/ Send a command to the specified app
GET /api/{nodeId}/{appId}/config/ Return the settings for the specified app
POST /api/{nodeId}/{appId}/config/ Adjust the settings for the specified app
GET /api/{nodeId}/{appId}/export/ Full recursive export for the specified app
POST /api/{nodeId}/{appId}/import/ Full recursive import for the specified app
POST /api/{nodeId}/{appId}/license/ Set the license for the specified app
POST /api/{nodeId}/{appId}/licenserequest/ Request a license for the specified app
GET /api/{nodeId}/{appId}/models/ List all models that can be added in the specified app
GET /api/{nodeId}/{appId}/tree/ Return the highest level tree for the specified app
GET /api/{nodeId}/{appId}/view/ Return the schema and settings for the specified app
Operations on a specified object (api_object)
GET /api/{nodeId}/{appId}/{objectId}/children/ List the direct children of the specified object
POST /api/{nodeId}/{appId}/{objectId}/command/ Send a command to the specified object
GET /api/{nodeId}/{appId}/{objectId}/config/ Return the settings for the specified object
POST /api/{nodeId}/{appId}/{objectId}/config/ Adjust the settings for the specified object
POST /api/{nodeId}/{appId}/{objectId}/copy/ Create a recursive copy of the specified object
POST /api/{nodeId}/{appId}/{objectId}/delete/ Delete the specified object
GET /api/{nodeId}/{appId}/{objectId}/export/ Full recursive export for the specified object
POST /api/{nodeId}/{appId}/{objectId}/import/ Full recursive import for the specified object
GET /api/{nodeId}/{appId}/{objectId}/tree/ Return the highest level tree for the specified object
GET /api/{nodeId}/{appId}/{objectId}/view/ Return the schema and settings for the specified object
GET /api/{nodeId}/{appId}/{objectId}/{objectType}/children/ List all children of the specified object that are of the specified type
Operations involving a specified object type within a specified app (api_objectType)
GET /api/{nodeId}/{appId}/{objectType}/add/ Return the default schema for the specified object type
POST /api/{nodeId}/{appId}/{objectType}/add/ Create a new instance of the specified object type under the specified app
GET /api/{nodeId}/{appId}/{objectType}/allconfig/ List all objects of the specified type under the specified app, along with their settings
GET /api/{nodeId}/{appId}/{objectType}/listing/ List all instances of the specified object type under the specified app
GET /api/{nodeId}/{appId}/{objectType}/newview/ Return a schema file filled with default values in order to display new items in UI
Log file handling (log)
POST /log/delete/{applabel}/ Delete all logs under the specified app label
POST /log/delete/{applabel}/{filename}/ Delete the specified log file
GET /log/download/{applabel}/{filename}/ Return the contents of the specified log file
GET /log/getlogs/ List all available logs
GET /log/zip/ Create a zip file containing all logs
General system information (system)