Muster RESTful HTTP API
The Muster RESTful API allows developer to query and interact with the Dispatcher service using HTTP requests parsed through the Muster builtin web server.
The API is available under the /api subfolder of the Web server and it's actually used by the Muster web server itself to provide its user interface.
http://{your.muster.webserver}:9790/api/
General info about web methods
Authentication and Token
Any method call expects an input token required to identify the current user or device session. The /login method is required to authenticate an user and get back the token required for the subsequent API calls that requires an authentication.
Required Parameters and Optional Parameters
In this guide all optional parameters are enclosed in square bracket. All other parameters are required.
Json and Xml format
All methods support json or xml formats for request/response data.
You can specify format parameters in QueryString or in a Content-Type request header:
QueryString sample:
- $format=json | xml
- format=json | xml
Request Header sample:
Content-Type: text/xml | application/json
Muster server analyse the format parameter in this sequence:
- “$format” in querystring
- if not provided, the server search “format” in querystring
- if not provided, the server search “content-type” in request header
- if not provided, the server sets “json” as default request/response format
Methods Return
All the methods return a ResponseStatus element that's required to check if a call has been successfully or to retrieve the error code and description.
The ResponseStatus object contains a code, a description and a response time:
Member | Type | Meaning |
---|---|---|
Code | Number | The HTTP Response status code |
Time | Number | A C time value in seconds |
Description | String | A string describing the status response |
The code inherits from the standard HTTP response codes:
Code | Meaning | Description |
---|---|---|
200 | No error | The operation completed successfully |
400 | Malformed request | The request is malformed or you did not sent all the required fields in the request |
403 | Unauthorised action | An unauthorised action was denied. This may be returned also if you do not supply an authentication token or a wrong one |
401 | Wrong username or password | The authentication attempt failed |
For further information you can take a look the following RFC: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
Along with a ResponseStatus member, a typical response will also include a ResponseData member, This is a typical request to login on the web server with the authToken inside the ResponseData member:
http://musterserver:9790/api/login?username=admin&password=mypassword
This is a typical response reported back from the server after the authentication:
Requests
Any request may be required to provide data to the server in order to perform a particular action. Data must be encapsulated inside a RequestData JSON encoded POST. The following example changes the password of the user associated with the current authorization token:
Login URLs
Configuration URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/configuration/list | Retrieves the Dispatcher configuration | A member for each Dispatcher section | A JSON array of configuration sections | |
example | ||||
/api/configuration/actions | Performs an action on the Dispatcher | name | ||
configure | Changes a configuration parameter | |||
example | ||||
softRestart | Sends a soft restart to the Dispatcher service | |||
example | ||||
startAutoscan | Starts an autoscan of available and unconnected nodes on the network | |||
example | ||||
swapEngineStatus | Changes the selection status of the Dispatcher engine | |||
example | ||||
importQueue | Imports a queue SQL into the Dispatcher database | |||
example | ||||
exportQueue | Exports the Dispatcher queue as SQL | |||
example | ||||
registerHost | Register a new host into the instances queue | |||
example |
Queue URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/queue/list | Retrieve the jobs queue | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | queue | A JSON array of jobs |
example | ||||
/api/queue/actions | Performs an action on the jobs queue | name | Expects an action in the name parameter | |
createFolder | Creates a folder in the queue | |||
example | ||||
submit | Submits a new job in the queue | |||
example | ||||
edit | Edit an existing job in the queue | |||
example | ||||
pause | Pauses one or more jobs | |||
example | ||||
resume | Resumes one or more jobs | |||
example | ||||
reinit | Reinits one or more jobs | |||
example | ||||
killAndGoOn | Kills and go on one or more jobs | |||
example | ||||
killAndPause | Kills and pause on one or more jobs | |||
example | ||||
killAndRedo | Kills and redo on one or more jobs | |||
example | ||||
remove | Deletes one or more jobs | |||
example | ||||
rename | Renames one or more jobs | |||
example | ||||
startsOn | Changes the starting time of one or more jobs | |||
example | ||||
resumeOn | Changes the resuming time of one or more jobs | |||
example | ||||
pauseOn | Changes the pausing time of one or more jobs | |||
example | ||||
setProject | Changes project (group) of one or more jobs | |||
example | ||||
setDepartment | Changes department of one or more jobs | |||
example | ||||
setPriority | Changes priority of one or more jobs | |||
example | ||||
setMaximumInstances | Changes maximum instances of one or more jobs | |||
example | ||||
setDependanciesIds | Changes the dependancies of one or more jobs | |||
example | ||||
setDependMode | Changes the dependancies check mode of one or more jobs | |||
example | ||||
setPools | Changes the destination pools of one or more jobs | |||
example | ||||
setExcludedPools | Changes the excluded pools of one or more jobs | |||
example | ||||
setOwner | Changes the owner of one or more jobs | |||
example | ||||
setNotes | Changes the notes of one or more jobs | |||
example | ||||
lock | Locks one or more jobs | |||
example | ||||
unlock | Unlocks one or more jobs | |||
example | ||||
archive | Archives one or more jobs | |||
example | ||||
unarchive | Unarchives one or more jobs | |||
example | ||||
reparent | Changes the parent folder of one or more jobs | |||
example | ||||
setMinimumLogicalUnits | Changes the minimum logical units of one or more jobs | |||
example | ||||
setMinimumCores | Changes the minimum cores of one or more jobs | |||
example | ||||
setMinimumDiskSpaceAmount | Changes the minimum disk space amount of one or more jobs | |||
example | ||||
setMinimumPhysicalUnits | Changes the minimum physical units of one or more jobs | |||
example | ||||
setMinimumCoresSpeed | Changes the minimum cores speed of one or more jobs | |||
example | ||||
setMinimumRamAmount | Changes the minimum ram amount of one or more jobs | |||
example | ||||
setProcessValidExitCodes | Changes the valid exit codes of one or more jobs | |||
example | ||||
setProcessWarningExitCodes | Changes the warning exit codes of one or more jobs | |||
example | ||||
setProcessErrorExitCodes | Changes the error exit codes of one or more jobs | |||
example | ||||
setProcessValidLogTexts | Changes the valid logs strings of one or more jobs | |||
example | ||||
setProcessWarningLogTexts | Changes the warning logs strings of one or more jobs | |||
example | ||||
setProcessErrorLogTexts | Changes the error logs strings of one or more jobs | |||
example | ||||
setFramesPrefixPath | Changes the frames prefix path of one or more jobs | |||
example | ||||
setMissingFramesCheck | Changes the missing frames check parameters of one or more jobs | |||
example | ||||
/api/chunks/list | Retrieve the chunks queue | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | chunks | A JSON array of chunks |
example | ||||
/api/chunks/actions | Performs an action on the chunks queue | name | Expects an action in the name parameter | |
setOnHold | Resets a chunk on hold | |||
example | ||||
setDone | Flags a chunk as completed | |||
example |
Instances URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/instances/list | Retrieve the instances queue | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | instances | A JSON array of instances |
example | ||||
/api/instances/actions | Performs an action on the instances queue | name | Expects an action in the name parameter | |
pause | Pauses an instance | |||
example | ||||
resume | Resumes an instance | |||
example | ||||
remove | Removes an offline instance | |||
example | ||||
killAndGoOn | Sends kill and go on an instance | |||
example | ||||
killAndPause | Sends kill and pause on an instance | |||
example | ||||
killAndRedo | Sends kill and redo on an instance | |||
example | ||||
refresh | Forces a refresh status on an instance | |||
example | ||||
softRestart | Sends a soft restart to an instance | |||
example | ||||
changeProcessPriority | Changes the process priority of an instance | |||
example | ||||
changeNotes | Changes notes of an instanace | |||
example | ||||
sysEvent | Sends a system event to an instance | |||
example | ||||
purgeJobs | Purges the jobs exclusion list of an instance | |||
example | ||||
purgeTemplates | Purges the templates exclusion list of an instance | |||
example |
Logs URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/logs/list | Retrieve the logs queue | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | logs | A JSON array of logs |
example | ||||
/api/logs/actions | Performs an action on the logs queue | name | Expects an action in the name parameter | |
clear | Clears the logs queue | |||
example |
History URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/history/list | Retrieve the history queue | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | history | A JSON array of history records |
example | ||||
/api/history/info | Retrieve the history boundaries and samples count | startingTime, endingTime, samples | A ResponseData member with the history infos | |
example | ||||
/api/history/actions | Performs an action on the history queue | name | Expects an action in the name parameter | |
clearRange | Clears an history queue time range | |||
example |
Statistics URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/statistics/list | Retrieve the statistics queue | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | statistics | A JSON array of statistics records |
example | ||||
/api/statistics/info | Retrieve the statistics boundaries and samples count | startingTime, endingTime, samples | A ResponseData member with the statistics infos | |
example | ||||
/api/statistics/actions | Performs an action on the statistics queue | name | Expects an action in the name parameter | |
clearRange | Clears a statistics queue time range | |||
example |
Templates URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/templates/list | Retrieve the templates list | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | templates | A JSON array of templates records |
example | ||||
/api/templates/fieldChanged | Requests events for a field content change. This will trigger the template Python callback and reports any field to be changed according | even | A JSON array of templates fields events | |
example |
Pools URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/pools/list | Retrieve the pools list | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | pools | A JSON array of pools records |
example | ||||
/api/pools/actions | Performs an action on the pools queue | name | ||
configure | Configures an existing pools | |||
example | ||||
add | Adds a new pool | |||
example | ||||
remove | Remove an existing pool | |||
example | ||||
notifyChanges | Notifies configuration changes to the Consoles | |||
example |
Users and groups URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/users/changepassword | Changes the password of the user associated with the current session | |||
example | ||||
/api/users/list | Retrieve the users list | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | users | A JSON array of users |
example | ||||
/api/users/actions | Performs an action on the jobs queue | name | ||
configure | Configures an existing user | |||
example | ||||
add | Adds a new user | |||
example | ||||
remove | Remove an existing user | |||
example | ||||
/api/groups/list | Retrieve the groups list | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | groups | A JSON array of groups |
example | ||||
/api/groups/actions | Performs an action on the jobs queue | name | Expects an action in the name parameter | |
configure | Configures an existing group | |||
example | ||||
add | Adds a new group | |||
example | ||||
remove | Remove an existing group | |||
example |
Repositories URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/repositories/list | Retrieves the repositories list | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | paths | A JSON array of repositories records |
example | ||||
/api/repositories/actions | Performs an action on the repositories queue | name | ||
add | Adds a new repository | |||
example | ||||
remove | Removes an existing repository | |||
example | ||||
configure | Configures an existing repository | |||
example | ||||
/api/repositories/browse | Retrieves files and folders from a repository | [$select],[$top/$take],[$skip],[$orderby],[$filter:[path],[showhiddenfiles],[isFolder],[extension]],$[inlinecount] | paths | A JSON array of files and folders |
example |
Mails URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/mails/list | Retrieves the mailing lists | [$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount] | mails | A JSON array of mails records |
example | ||||
/api/mails/actions | Performs an action on the mailing list | name | ||
add | Adds a new mailing list | |||
example | ||||
remove | Removes an existing mailing list | |||
example | ||||
configure | Configures an existing mailing list | |||
example |
Helper URLs
URL address | Used to | Expected parameters | ResponseData members | Meaning |
---|---|---|---|---|
/api/keepalive | Keep alive the client authentication token | authToken | None | Refreshes the client authentication status |