Using the Management Console APIs
The management console provides REST APIs that you can use to programmatically access much of the console’s functionality. Using these REST APIs, you can:
-
Register new servers and manage existing servers, including restarting servers.
-
Manage server groups.
-
Access and manage files on servers.
For details on these operations, see Managing Servers Using REST APIs.
[mmc:Mule 3.2] In addition, you can use the REST APIs to:
-
Create or remove a cluster and get information about a cluster, as well as start, stop, and restart applications on a cluster. For details see Managing Clusters Using REST APIs.
-
Find, upload, and delete applications inside the repository. For details see Managing Applications Using REST APIs.
-
Deploy, undeploy, create, update, and delete deployments inside a server or cluster. For details see Managing Deployments Using REST APIs.
-
Manage flows, including finding, starting, and stopping flows as well as finding, starting, and stopping a flow’s endpoints. For details about managing flows in a server see Managing Flows in a Server Using REST APIs. For details about managing flows in a cluster see Managing Flows in a Cluster Using REST APIs.
Overview
Representational State Transfer (REST) is a style of software architecture. An important concept in REST is the existence of resources, each of which can be referred to using a global identifier. Specifically, both data and functionality are considered resources. Using the REST APIs, you access functionality by specifying a URL, or link, to that functionality – this is also commonly referred to as a method. Data representation is passed to and from a REST API method in the form of a JavaScript Object Notation (JSON) object.
In brief, here’s how you use the REST APIs:
-
Set up any parameters that may need to be passed to the API. You set the parameter values in a JSON object.
-
Build the request. The request consists of the full URL of the resource, plus the name of any parameters and their values.
-
Invoke the request with the appropriate HTTP method: GET, PUT, DELETE, or POST.
-
Get the response. If you retrieve information, parse the response for the data you need. You can use response data for further API requests, if needed.
You can use any HTTP client to access the APIs. Note that all management console APIs use JSON instead of XML for the data format.
If you are programming in Java, it’s recommended that you use the [Jersey client. Or, for JSON support, use the HttpClient with Jackson, the high-performance JSON processor.
An Example
As an example, here is how to use a REST API to perform a console-related operation - in this case, listing all servers. The URL for this resource (method) is /mmc/api/servers and the HTTP method to invoke the request is GET. Here’s what the request would look like if you submitted it as a command using cURL, the command line HTTP tool:
curl --basic -u admin:admin http://localhost:8080/mmc/api/servers
The response you get would be in JSON format, and look something like this:
{
"name" : "Test",
"id" : "local$b15ecba1-9f97-4b16-8127-9b137cdbb2e1",
"href" : "http://localhost:8080/mmc/api/servers/local$b15ecba1-9f97-4b16-8127-9b137cdbb2e1",
"agentUrl" : "https://localhost:7777/mmc-support",
"hostIp" : "192.168.0.13",
"muleServerId" : "d9505d40-2c5c-11df-b832-a32a5a09ec4e",
"started" : "Wed Mar 10 16:51:59 CET 2010",
"version" : "2.2.5",
"agents": [
{
"name" : "mmc-support",
"description" : "Mule Management Console Support (0.0.0.0:7777)"
},
{
"name" : "jmx-agent",
"description" : "JMX Agent"
}
],
"groups" : [
{
"name" : "Development",
"href" : "http://localhost:8080/mmc/api/serverGroups/73d89173-290e-4cb3-a61c-e11deb74767d"
}
],
"runningServices" : 3,
"pausedServices" : 0,
"stoppedServices": 0
}You could then parse the response for the data you need.
Status and Error Handling Codes
All console REST APIs return the same set of status codes. You can expect any call to a REST API to return one of the following status codes:
| Status Code | Description |
|---|---|
200 |
The operation was successful. |
201 |
The resource (for example, a server or server group) was created. The Location header in the response contains the location of the resource. |
404 |
The resource was not found. |
409 |
When the method attempted to create a resource (such as a server or server group), the operation was unsuccessful because a resource with that name already exists. |
500 |
The operation was unsuccessful. See the HTTP body for details. |
For errors that generate a 500 status code, the HTTP response contains a JSON response with a specific error message. Check the JSON response in the HTTP response to determine what caused the error. For example:
500
Content-Type: application/json
Server: Apache-Coyote/1.1
Date: Sun, 08 Nov 2009 00:12:55 GMT
{
message : "Could not connect to remote server."
}