GET

Use the HTTP GET method with the installation resource to request information about the installation that the administrative REST API runs in.

The information that is returned is similar to the information that is returned by the dspmqver control command.

Resource URL
Optional query parameters
Request headers
Request body format
Security requirements
Response status codes
Response headers
Response body format
Examples

Resource URL

[V9.0.4 Oct 2017] IBM® MQ 9.0.4 and later:

https://host:port/ibmmq/rest/v1/admin/installation/{installationName}

IBM MQ 9.0.3 and earlier:

https://host:port/ibmmq/rest/v1/installation/{installationName}

installationName: Optionally specifies the name of the installation to query. This name must be the name of the installation that the REST API is running in.

[V9.0.1 Nov 2016] You can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring HTTP and HTTPS ports.

Optional query parameters

attributes={extended|*|extended.attributeName,...}

extended

Specifies that all extended attributes are returned.

*

Specifies all attributes. This parameter is equivalent to extended.

extended.attributeName,...

Specifies a comma-separated list of extended attributes to return:

level: String.; IBM MQ build level.
operatingSystem: This attribute is only available on z/OS®, UNIX, Linux®, and Windows.; String.; Full descriptive text of the operating system.
hostName: String.; System host name.; If the system has multiple hosts, only one name is returned.
description: This attribute is only available on UNIX, Linux, and Windows.; String.; Installation description.
installationPath: This attribute is only available on UNIX, Linux, and Windows.; String.; The path to the installation.
dataPath: This attribute is only available on UNIX, Linux, and Windows.; String.; The path to where the data for the installation is stored.
maximumCommandLevel: This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.; Integer.; Maximum command level that is supported.
primary: This attribute is only available on UNIX, Linux, and Windows.; Boolean.; Primary installation status.

Request headers

The following headers must be sent with the request:

Authorization: This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.

Request body format

None.

Security requirements

[V9.0.2 Mar 2017] The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. For more information about security for the administrative REST API, see IBM MQ Console and REST API security.

There are no specific authorization requirements for an HTTP GET on the installation resource.

Response status codes

200: Installation information retrieved successfully.
400: Invalid data provided.; For example, invalid installation attributes specified.
401: Not authenticated.; The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. For more information, see Security requirements.
404: Installation does not exist.
500: Server issue or error code from IBM MQ.

Response headers

The following headers are returned with the response:

Content-Type: This header is returned with a value of application/json;charset=utf-8.

Response body format

The response is in JSON format in UTF-8 encoding. The response contains an outer JSON object that contains a single JSON array called installation. Each element in the array is a JSON object that represents information about an installation. Each JSON object contains the following attributes:

name

This attribute is only available on UNIX, Linux, and Windows.

String.

The installation name.

version

String.

The version of IBM MQ for the installation.

platform

String.

One of the following values:

appliance
ibm-i
unix
windows
z/os

extended

JSON object.

If requested, contains one or more of the following extra properties:

level: String.; IBM MQ build level.
operatingSystem: This attribute is only available on z/OS, UNIX, Linux, and Windows.; String.; Full descriptive text of the operating system.
hostName: String.; System host name.; If the system has multiple hosts, only one name is returned.
description: This attribute is only available on UNIX, Linux, and Windows.; String.; Installation description.
installationPath: This attribute is only available on UNIX, Linux, and Windows.; String.; The path to the installation.
dataPath: This attribute is only available on UNIX, Linux, and Windows.; String.; The path to where the data for the installation is stored.
maximumCommandLevel: This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.; Integer.; Maximum command level that is supported.
primary: This attribute is only available on UNIX, Linux, and Windows.; Boolean.; Primary installation status.

If an error occurs, the response body contains an error message. For more information, see REST API error handling.

Examples for UNIX, Linux, and Windows

The following example gets basic information about the installation that the REST API is running in. The following URL is used with the HTTP GET method:
IBM MQ 9.0.4 and later:
```
https://localhost:9443/ibmmq/rest/v1/admin/installation
```
IBM MQ 9.0.3 and earlier:
```
https://localhost:9443/ibmmq/rest/v1/installation
```
The following JSON response is returned:
```
{
    "installation": 
    [{
       "name": "Installation1",
       "platform": "windows",
       "version": "9.0.0.0"
    }]
}
```

The following example gets extended information about the installation Installation1. The following URL is used with the HTTP GET method:

IBM MQ 9.0.4 and later:

https://localhost:9443/ibmmq/rest/v1/admin/installation/Installation1?attributes=*

IBM MQ 9.0.3 and earlier:

https://localhost:9443/ibmmq/rest/v1/installation/Installation1?attributes=*

The following JSON response is returned:

{
    "installation": 
    [{
         "extended": {
             "dataPath": "C:\\Program Files (x86)\\IBM\\WebSphere MQ",
             "description": "My MQ installation",
             "hostName": "exampleHost",
             "installationPath": "C:\\Program Files\\IBM\\WebSphere MQ",
             "level": "p900-L160614",
             "maximumCommandLevel": 900,
             "operatingSystem": "Windows 7 Professional x64 Edition, Build 7601: SP1",
             "primary": true
         },
         "name": "Installation1",
         "platform": "windows",
         "version": "9.0.0.0"
    }]
}

The following example gets the installation path and host name for Installation1. The following URL is used with the HTTP GET method:

IBM MQ 9.0.4 and later:

https://localhost:9443/ibmmq/rest/v1/admin/installation/Installation1?attributes=extended.installationPath,extended.hostName

IBM MQ 9.0.3 and earlier:

https://localhost:9443/ibmmq/rest/v1/installation/Installation1?attributes=extended.installationPath,extended.hostName

The following JSON response is returned:

{
    "installation": [{
        "extended": {
            "hostName": "exampleHost",
            "installationPath": "C:\\Program Files\\IBM\\MQ"
         },
         "name": "Installation1",
         "platform": "windows",
         "version": "9.0.1.0"
    }]
}

Examples for z/OS

The following example gets basic information about the installation. The following URL is used with the HTTP GET method:

IBM MQ 9.0.4 and later:

https://REST.example.com:9443/ibmmq/rest/v1/admin/installation

IBM MQ 9.0.3 and earlier:

https://REST.example.com:9443/ibmmq/rest/v1/installation

The following JSON response is returned:

{
    "installation": [{
       "platform": "z/os",
       "version": "9.0.1"
    }]
}

The following example gets extended information about the installation. The following URL is used with the HTTP GET method:

IBM MQ 9.0.4 and later:

https://REST.example.com:9443/ibmmq/rest/v1/admin/installation?attributes=extended

IBM MQ 9.0.3 and earlier:

https://REST.example.com:9443/ibmmq/rest/v1/installation?attributes=extended

The following JSON response is returned:

{
    "installation": [{
       "extended": {
           "hostName": "REST.example.com",
           "level": "V901-L161011",
           "operatingSystem": "z/OS 01.00 02"
       },
       "platform": "z/os",
       "version": "9.0.1"
   }]
}