Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

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:

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:


         
      
1
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:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "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:


         
      
1
2
3
4
5
6
7
8
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."
}