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/

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 set “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:

MemberTypeMeaning
CodeNumberThe HTTP Response status code
TimeNumberA C time value in seconds
DescriptionStringA string describing the status response

The code inherits from the standard HTTP response codes:

CodeMeaningDescription
200No errorThe operation completed successfully
400Malformed requestThe request is malformed or you did not sent all the required fields in the request
403Unauthorised actionAn unauthorised action was denied. This may be returned also if you do not supply an authentication token or a wrong one
401Wrong username or passwordThe 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:

URL

Post data

Typical response

URL addressUsed toExpected parametersResponseData membersMeaning
/api/loginLogin on the Muster HTTP serverusername,passwordauthTokenAn authorization token to be used for successive API calls
example
/api/logoutUsed to logout and invalidate the authorization tokenauthTokenNone
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/configuration/listRetrieves the Dispatcher configuration A member for each Dispatcher sectionA JSON array of configuration sections
example
/api/configuration/actionsPerforms an action on the Dispatchername
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
URL addressUsed toExpected parametersResponseData membersMeaning
/api/queue/listRetrieve the jobs queue[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]queueA JSON array of jobs
example
/api/queue/actionsPerforms an action on the jobs queuenameExpects 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/listRetrieve the chunks queue[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]chunksA JSON array of chunks
example
/api/chunks/actionsPerforms an action on the chunks queuenameExpects an action in the name parameter
setOnHold Resets a chunk on hold
example
setDone Flags a chunk as completed
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/instances/listRetrieve the instances queue[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]instancesA JSON array of instances
example
/api/instances/actionsPerforms an action on the instances queuenameExpects 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
URL addressUsed toExpected parametersResponseData membersMeaning
/api/logs/listRetrieve the logs queue[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]logsA JSON array of logs
example
/api/logs/actionsPerforms an action on the logs queuenameExpects an action in the name parameter
clear Clears the logs queue
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/history/listRetrieve the history queue[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]historyA JSON array of history records
example
/api/history/infoRetrieve the history boundaries and samples count startingTime, endingTime, samplesA ResponseData member with the history infos
example
/api/history/actionsPerforms an action on the history queuenameExpects an action in the name parameter
clearRange Clears an history queue time range
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/statistics/listRetrieve the statistics queue[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]statisticsA JSON array of statistics records
example
/api/statistics/infoRetrieve the statistics boundaries and samples count startingTime, endingTime, samplesA ResponseData member with the statistics infos
example
/api/statistics/actionsPerforms an action on the statistics queuenameExpects an action in the name parameter
clearRange Clears a statistics queue time range
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/templates/listRetrieve the templates list[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]templatesA JSON array of templates records
example
/api/templates/fieldChangedRequests events for a field content change. This will trigger the template Python callback and reports any field to be changed accordingevenA JSON array of templates fields events
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/pools/listRetrieve the pools list[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]poolsA JSON array of pools records
example
/api/pools/actionsPerforms an action on the pools queuename
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
URL addressUsed toExpected parametersResponseData membersMeaning
/api/users/changepasswordChanges the password of the user associated with the current session
example
/api/users/listRetrieve the users list[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]usersA JSON array of users
example
/api/users/actionsPerforms an action on the jobs queuename
configure Configures an existing user
example
add Adds a new user
example
remove Remove an existing user
example
/api/groups/listRetrieve the groups list[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]groupsA JSON array of groups
example
/api/groups/actionsPerforms an action on the jobs queuenameExpects an action in the name parameter
configure Configures an existing group
example
add Adds a new group
example
remove Remove an existing group
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/repositories/listRetrieves the repositories list[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]pathsA JSON array of repositories records
example
/api/repositories/actionsPerforms an action on the repositories queuename
add Adds a new repository
example
remove Removes an existing repository
example
configure Configures an existing repository
example
/api/repositories/browseRetrieves files and folders from a repository[$select],[$top/$take],[$skip],[$orderby],[$filter:[path],[showhiddenfiles],[isFolder],[extension]],$[inlinecount]pathsA JSON array of files and folders
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/mails/listRetrieves the mailing lists[$select],[$top/$take],[$skip],[$orderby],[$filter],$[inlinecount]mailsA JSON array of mails records
example
/api/mails/actionsPerforms an action on the mailing listname
add Adds a new mailing list
example
remove Removes an existing mailing list
example
configure Configures an existing mailing list
example
URL addressUsed toExpected parametersResponseData membersMeaning
/api/keepaliveKeep alive the client authentication tokenauthTokenVariable number of membersReturns a variable number of members describing the client environment