API Documentation

1 OpenAPI Document
2 Swagger
3 Authentication
4 Error Codes
5 Response
6 Endpoints

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.

Using Swagger Editor on the web

With Swagger Editor, you can view and edit the OpenAPI document inside your browser, while previewing the documentation in real time.

Visit SwaggerEditor and select File → Import file, or drag-and-drop the openapi.json file into the browser window.

You can then view and make edits to the OpenAPI document in the left panel (in YAML format) and visualize the UI in the right panel, or simply drag the divider all the way to the left if you are only interested in the UI.

Note: This method will allow you to view the documentation in Swagger UI, but you will only be able to interact with the API if it can be accessed from a public URL/IP address. In that case, replace http://localhost:5000/ in the url field with the correct address. Otherwise, you will need to install locally (see below) on the system that is running the Django backend in order to issue API calls through Swagger UI.

Starting with Open API version 3.1.0, a new Swagger Editor was release (this is the linked version above)

Legacy Open API Swagger Editor which supports versions 3.0.X can be accessed by visiting Swagger Editor

Installing Swagger Editor locally

Swagger Editor can also be installed locally with GitHub - swagger-api/swagger-editor: 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 or drag-and-drop into the browser window.

Using Swagger UI standalone

If you do not need to view or edit the OpenAPI document, you can also use a standalone version of Swagger UI.

The tool GitHub - vajahath/open-swagger-ui: A handy CLI / API to open swagger doc in swagger ui. will allow you to open a local openapi.json file in the Swagger UI.

It requires Node.js >=10 and can be installed via npm:

npm i -g open-swagger-ui

Then, make sure you are in the directory containing openapi.json (or point the command to where it is located) and run:

open-swagger-ui .\openapi.json --open

Authentication

In order to use the API, you will need to provide an authorization token.

You can generate an authentication token from your username and password with a status: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.

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.

If you are using something like Postman, click on Headers and add these, replacing 123abc with your token.

Error Codes

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

200 - Successful operation

401 - Unauthorized (see Authentication)

4xx/5xx - Request failed for some other reason

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 status: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.

status:POST /accounts/api-token-auth/ Generate API token to authorize session
status:POST /accounts/changePassword/ Change the password of the specified user

status:GET /api/folder/{folderId}/tree/ Return a tree containing all children of the specified folder
status:GET /api/request/{requestId}/ Return the contents of the specified request
status:GET /api/status/ Report the status of the API backend, including mode
status:GET /api/tree/ Return the highest level tree for this install
status:GET /api/{entity}/allconfig/ Return a full listing of an entity type (nodes, apps, objects)
status:GET /api/{entity}/allconfigfromtypes/ Return a full listing of an entity type (nodes, apps, objects)
status:GET /api/{schemaId}/schema/ Return the schema file for the specified schema ID
status:GET /api/itemTypes Return list of schema item types
status:GET /api/schema/ Return the schema files for the specified schema IDs
status:POST /api/{category}/{itemId}/move/ Move node or folder to new location
status:POST /api/folder/add/ Add new folder
status:GET /api/folder/{folderId}/view/ Get folder properties
status:POST /api/folder/{folderId}/delete/Delete folder
status:GET /api/folder/{folderId}/config/ Get folder configurations
status:POST /api/folder/{folderId}/config/Adjust the settings of the specified node

status:GET /api/{nodeId}/apps/ Return a list of all apps under the specified node
status:POST /api/{nodeId}/command/ Send a command to the specified node
status:GET /api/{nodeId}/config/ Return the settings for the specified node
status:POST /api/{nodeId}/config/ Adjust the settings for the specified node
status:POST /api/{nodeId}/delete/ Delete the specified node from the remote manager database
status:GET /api/{nodeId}/export/ Full recursive export for the specified node
status:POST /api/{nodeId}/import/ Full recursive import for the specified node
status:POST /api/{nodeId}/sync/ Sync the specified node to the remote manager
status:GET /api/{nodeId}/tree/ Return the highest level tree for the specified node
status:GET /api/{nodeId}/view/ Return the schema and settings for the specified node
status:GET /api/{nodeId}/defaults/ Return node defaults configurations

status:POST /api/{nodeId}/{appId}/command/ Send a command to the specified app
status:GET /api/{nodeId}/{appId}/config/ Return the settings for the specified app
status:POST /api/{nodeId}/{appId}/config/ Adjust the settings for the specified app
status:GET /api/{nodeId}/{appId}/export/ Full recursive export for the specified app
status:POST /api/{nodeId}/{appId}/import/ Full recursive import for the specified app
status:POST /api/{nodeId}/{appId}/license/ Set the license for the specified app
status:POST /api/{nodeId}/{appId}/licenserequest/ Request a license for the specified app
status:GET /api/{nodeId}/{appId}/models/ List all models that can be added in the specified app
status:GET /api/{nodeId}/{appId}/tree/ Return the highest level tree for the specified app
status:GET /api/{nodeId}/{appId}/view/ Return the schema and settings for the specified app
status:GET /api/{appId}/{schemaId}/get_metadata/ Return metadata properties associated with the schema for the specified app
status:GET /api/{appId}/{schemaId}/metadata_schema/ Return schema injected with the properties for the specified app

status:GET /api/{nodeId}/{appId}/{objectId}/children/ List the direct children of the specified object
status:POST /api/{nodeId}/{appId}/{objectId}/command/ Send a command to the specified object
status:GET /api/{nodeId}/{appId}/{objectId}/config/ Return the settings for the specified object
status:POST /api/{nodeId}/{appId}/{objectId}/config/ Adjust the settings for the specified object
status:POST /api/{nodeId}/{appId}/{objectId}/copy/ Create a recursive copy of the specified object
status:POST /api/{nodeId}/{appId}/{objectId}/delete/ Delete the specified object
status:GET /api/{nodeId}/{appId}/{objectId}/export/ Full recursive export for the specified object
status:POST /api/{nodeId}/{appId}/{objectId}/import/ Full recursive import for the specified object
status:GET /api/{nodeId}/{appId}/{objectId}/tree/ Return the highest level tree for the specified object
status:GET /api/{nodeId}/{appId}/{objectId}/view/ Return the schema and settings for the specified object
status:GET /api/{nodeId}/{appId}/{objectId}/{objectType}/children/ List all children of the specified object that are of the specified type

status:GET /api/{nodeId}/{appId}/{objectType}/add/ Return the default schema for the specified object type
status:POST /api/{nodeId}/{appId}/{objectType}/add/ Create a new instance of the specified object type under the specified app
status:GET /api/{nodeId}/{appId}/{objectType}/allconfig/ List all objects of the specified type under the specified app, along with their settings
status:GET /api/{nodeId}/{appId}/{objectType}/listing/ List all instances of the specified object type under the specified app
status:GET /api/{nodeId}/{appId}/{objectType}/newview/ Return a schema file filled with default values in order to display new items in UI

status:POST /log/delete/{applabel}/ Delete all logs under the specified app label
status:POST /log/delete/{applabel}/{filename}/ Delete the specified log file
status:GET /log/download/{applabel}/{filename}/ Return the contents of the specified log file
status:GET /log/getlogs/ List all available logs
status:GET /log/zip/ Create a zip file containing all logs
status:GET /log/gettextlogs/Get list of all logs
status:GET /log/query/{applabel}/{filename}/{count}/ Return the contents of the specified log file

status:GET /system/systemDateTime/ Return the current date and time for the system (in Unix Epoch time)
status:GET /system/systemInfo/ Return information about the system

status:GET /packagemanager/info/{installId}/ Return installed package details
status:GET /packagemanager/tree/ Return list of installed packages
status:GET /packagemanager/available/ Return list of packages that can be installed
status:GET /packagemanager/history/Return list of packages that were installed
status:POST /packagemanager/uploadModule/ Upload package for installation
status:POST /packagemanager/{nodeId}/delete/{packageId}/ Delete imported package
status:POST /packagemanager/{nodeId}/install/ Install package
status:POST /packagemanager/{nodeId}/uninstall/Uninstall package
status:POST /packagemanager/{nodeId}/remoteUpload/Remote upload packages

status:GET /dashboard/ Return list of nodes

status:GET /mqtt/{nodeId}/{action}/ Get node information
status:POST /mqtt/{nodeId}/{action}/ Perform action on node

Edge ACM User Guide