This article is about the Workgroup server REST API. To learn how to set up the Domain services REST API, see Enabling REST endpoint for Domain Services.
For the latest enhancements to the Workgroup server REST API, see the WGS REST API Release Notes.
APIs, or application programming interfaces, allow businesses to share information and automate business processes using a safe and secure communication standard.
To equip our customers with the ability to automate many of the manual processes that can be performed through Navigator, we have built a REST API and made it available to you. In addition, you can “test drive” our API without installing it by using Swagger UI, a user-friendly online tool that allows direct connections to APIs through an HTML-based user interface.
|
Jump ahead: |
Introduction
In this article, we will lead you through the steps required to perform two REST API operations. You’ll be performing them by connecting to your Navigator site using the Swagger UI.
|
To get started with |
Go to |
|
Navigator |
https://<Workgroup Server IP:Rest API port>/rest/v1/api-docs |
|
Navigator Security Management |
https://<Workgroup Server IP:Rest API port>/wsm/v1/api-docs |
For example, the Swagger UI for the Navigator demo site is:
https://navigator.meshiq.com:8019/rest/v1/api-docs
The Swagger UI for the Navigator Security Manager site is:
https://navigator.meshiq.com:8019/wsm/v1/api-docs
Viewing the Available Operations
Scroll down the page to look at the ibmMQ.queue section, which lists IBM MQ Queue Operations.
The image below shows Get, Post, and Delete, which are examples of methods. The first operation shown, Search Queues, is used to return a list of the queues that meet the specific criteria that you enter. Create queue creates a new queue on the queue manager that you specify.
As shown in the table below (taken from https://www.ibm.com/docs/en/ibm-mq/9.2?topic=comparison-queue-commands), REST API Operations are based on the REST API resource and HTTP method designed by IBM.
Logging in
First, provide the credentials that are needed to authorize you to access and use the site. There are two ways to do this.
Login option 1: Authorization using a curl command
As an alternative to using the Swagger user interface, you can obtain a REST API authorization token for login using the following curl command:
curl -X 'POST' \ '
http://localhost:8019/auth/token'
\ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "scope": "*", "username": "Admin", "password": "admin", "client_id": "client_test", "client_secret": "client_test_secure", "grant_type": "password"}'
Login option 2: Authorization using the Swagger user interface
You can log onto your Navigator site through the Swagger UI tool.
- Scroll to the top of the page and click the Authorize button on the right-hand side:
- Under basic authentication (basicAuth), enter the same user and password you would use to log in to https://navigator.meshiq.com/manage/#/login.
- Click Authorize. You are now logged in and the dialog is labeled “Authorized.”
- Click Close.
Example 1. Search Queues
Now we’ll do a search for queues on a given queue manager that begin with a certain letter or characters. For example, you can search for BANK* to find queues that begin with the word BANK.
Step 1. Enabling Methods with “Try it out”
Before trying any operation, you must first enable it so you can enter information.
Navigate back to GET /ibmmq/queues Search Queues and click on it to expand it. You will see the various parameters.
To enable data entry, click the Try it out button on the right: .
The button is now labeled “Cancel,” and the boxes are available for data entry.
Step 2. Parameters Selection
Criteria Selection
To specify the queue criteria:
- Enter the name of the queue manager in the QmgrName box (for example, QA).
- Enter the character or characters you are looking for in the queue name in the queueName criteria box (for example, BANK*).
- Click the Execute button that is below the parameters.
Step 3. Request and Response
As a response, we get a list of all queues with names that begin with “BANK.” on the QA queue manager.
- The entire result set is contained in brackets ([]).
- Each result record is contained in braces, or “curly brackets” ({}).
- Each line in the response is part of a name/value pair.
The line for each pair consists of:
- “attribute” in quotation marks
- A colon (:)
- The attribute value in quotation marks
- A comma (,) to separate the attribute from the next attribute
For example: "qmgrName": "QA",
[
{
"wgsName": "MQM",
"nodeName": "LEUNAME",
"qmgrName": "QA",
"name": "BANK.IN",
"type": "Local"
},
{
"wgsName": "MQM",
"nodeName": "LEUNAME",
"qmgrName": "QA",
"name": "BANK.OUT",
"type": "Local"
}
]
The response has returned five attributes. For more information on using the attributes parameter of Search Queues to choose the attributes for your result sets, see Customizing Queries by Specifying Attributes for the Result Set.
CURL Command Structures
A closer look at Swagger reveals that the Responses section includes the Curl command for our query, as well as the Request URL, which is part of the Curl command.
Curl Command:
curl -X GET "http://jenkins.nastel.com:8019/rest/v1/ibmmq/queues?nodeName=LEUNAME&qmgrName=QA&queueName=BANK%2A" -H "accept: application/json" -H "Authorization: Basic QWRtaW46YWRtaW4="
Request URL:
http://jenkins.nastel.com:8019/rest/v1/ibmmq/queues?nodeName=LEUNAME&qmgrName=QA&queueName=BANK%2A
|
? |
indicates the beginning of the query to pass the parameters |
|
& |
separates one parameter from another For example: qmgrName=QA &queueName=BANK%2A |
|
%2A |
In this example, %2A is a code for the asterisk. |
Example 2: Create a Queue
Now we’ll create a new queue called “TestQ” on the queue manager called QA.
Step 1. Enabling Methods with “Try it Out”
Navigate back to POST /ibmmq/queues Create Queue and click on it to expand it. You will see the various parameters.
To enable data entry, click the Try it out button on the right: .
The button is now labeled “Cancel.” The Request body becomes available for editing.
Step 2. Parameters Entry
As noted on the Swagger page, the required data values for this command are "nodeName", "qmgrName", "type", and "name".
- At a minimum, fill in the values for the required fields in the Request body.
- Click the Execute button that is below the Request body:
Step 3. Request and Response
Again, in Swagger, the Responses section includes the Curl command for our request, as well as the Request URL, which is a portion of the Curl command.
Request: JSON and CURL Command Structures
The Swagger UI uses the JSON data interchange format for requests and responses.
In JASON format, the request command looks like this:
{
"wgsName": "MQM",
"nodeName": "LEUNAME",
"qmgrName": "QA",
"name": "TestQ",
"type": "Local",
“uri”: “string” ,
}
The Curl command, which can be use in scripts, contains the information from the request (including the request URL, shown in bold). Since this is a POST command, we are not performing a query, so the question mark (?) that was in the search query is not included.
curl -X POST "http://jenkins.nastel.com:8019/rest/v1/ibmmq/queues" -H "accept: */*" -H "Authorization: Basic QWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d "{\"wgsName\":\"MQM\",\"nodeName\":\"LEUNAME\",\"qmgrName\":\"QA\",\"name\":\"TestQ\",\"type\":\"Local\",\"uri\":\"string\"}"
Here, the two are shown side-by-side:
|
JSON In JASON format, the request command looks like this:
|
Curl Attributes for the new queue are separated from one another by commas. Attribute names are separated from values by colons. |
{
|
|
Response
As shown below, the response of 201 indicates that the queue was created successfully.
Example 3: Search Queues for the New Queue
Following the steps from Example 1, we can now use GET /ibmmq/queues Search Queues with the new queue.
Step 1: Enabling Methods with “Try it out”
Navigate back to GET /ibmmq/queues Search Queues and click on it to expand it. If needed, click the Try it out button on the right: .
Step 2: Parameters Selection
To specify the queue criteria:
- Enter the name of the queue manager in the QmgrName box (for example, QA).
- Enter the queue name in the queueName criteria box (TestQ).
Step 3: Request and Response
The request and response are displayed on the Swagger UI.
Request
The request, shown in Curl format, is:
curl -X GET "http://jenkins.nastel.com:8019/rest/v1/ibmmq/queues?qmgrName=QA&queueName=TestQ" -H "accept: application/json" -H "Authorization: Basic QWRtaW46YWRtaW4="
Response
The response shows the newly created queue:
Additional Options
Swagger UI offers additional options for customizing requests. For example, you can list specific attributes for the result set, or even specify attribute sections.
|
Jump ahead: |
Customizing Queries by Specifying Attributes for the Result Set
By default, the response includes only the most basic queue attributes, such as the WorkGroup Server name, node name, queue manager name, queue name, and queue type.
To specify the exact attributes you want to return, use the attributes parameter:
|
Value |
Response |
|
* |
Returns all queue attributes |
|
Comma-separated list of attributes, for example: state.lastUpdated,state.createDate,state.createTime,state.curQDepth |
Returns the specifics attributes for each result record |
|
Group of attributes, for example: General.* |
Returns the specified group of attributes for each result record (for example, general, extended, cluster, event, and so on). |
Listing Specific Attributes
You can indicate the specific attributes that you want to include in your response by listing them in the attributes box. You must qualify each attribute by providing the section that each attribute is contained in.
Example: state.lastUpdated,state.createDate,state.createTime,state.curQDepth
Curl Command
When the attributes from the example above are included in a query, the curl command includes them as well, as shown in the bold portion of the text below (%2C represents a comma).
curl -X GET "http://navigator.meshiq.com:8019/rest/v1/ibmmq/queues?qmgrName=QM_PROD&queueName=CREDIT.%2A&attributes=state.lastUpdated%2Cstate.createDate%2Cstate.createTime%2Cstate.curQDepth" -H "accept: application/json" -H "Authorization: Basic ZGVtbzpkZW1v"
Response
The section that you specified and the four attributes that you listed are included in the response.
[
{
"wgsName": "MQM",
"nodeName": "IP-172-31-47-88",
"qmgrName": "QM_PROD",
"name": "CREDIT.INPUT.PROCESS",
"type": "Local",
"state": {
"lastUpdated": 1632838260000,
"createDate": "2019-12-03",
"createTime": "21.35.39",
"curQDepth": 0
}
},
{
"wgsName": "MQM",
"nodeName": "IP-172-31-47-88",
"qmgrName": "QM_PROD",
"name": "CREDIT.OUTPUT.PROCESS",
"type": "Local",
"state": {
"lastUpdated": 1632838260000,
"createDate": "2019-12-03",
"createTime": "21.36.04",
"curQDepth": 0
}
}
]
Specifying an Attribute Section
You can indicate a particular section that you want to include in your response by providing the section name followed by a period (.) and an asterisk.
Example:
General.*
Note: To include multiple sections, separate them with commas. For example:
general.*,extended.*
Curl Command
curl -X GET "http://navigator.meshiq.com:8019/rest/v1/ibmmq/queues?qmgrName=QM_PROD&queueName=CREDIT.%2A&attributes=general.%2A" -H "accept: application/json" -H "Authorization: Basic ZGVtbzpkZW1v"
Response
This time, the response includes all attributes from the section.
[
{
"wgsName": "MQM",
"nodeName": "IP-172-31-47-88",
"qmgrName": "QM_PROD",
"name": "CREDIT.INPUT.PROCESS",
"type": "Local",
"general": {
"description": "Credit Input Processing",
"usage": "Normal",
"scope": "QMgr",
"defBind": "On Open",
"defPersistence": "Not Persistent",
"inhibitPut": "Allowed",
"inhibitGet": "Allowed",
"defPriority": 0,
"custom": "",
"qsgDisp": "QMgr"
}
},
{
"wgsName": "MQM",
"nodeName": "IP-172-31-47-88",
"qmgrName": "QM_PROD",
"name": "CREDIT.OUTPUT.PROCESS",
"type": "Local",
"general": {
"description": "Credit Input Processing",
"usage": "Normal",
"scope": "QMgr",
"defBind": "On Open",
"defPersistence": "Not Persistent",
"inhibitPut": "Allowed",
"inhibitGet": "Allowed",
"defPriority": 0,
"custom": "",
"qsgDisp": "QMgr"
}
}
]
Viewing Schemas
The schemas for Create queue and other operations are available through Swagger UI. To view the schema, click the Schema link in the Request body area.
The Schema tab opens, with details about the attributes of the request.
- Attributes are listed on the left. A red asterisk (*) next to the name of the attribute indicates that it is required.
- The Queue Data column on the right-hand side shows the data type in blue (e.g., string) and descriptions of the attributes in bold face.
An angle bracket indicates that you can expand a section to show more. For example, you can click the angle bracket in front of an array to display the elements of an array:
Hover over a Pojo to view its endpoint:
Click its angle bracket to view its description and elements:
Issue Plain Text or JSON-formatted MQSC Commands through the REST API
You can submit administrative commands directly to a queue manager using the HTTP POST method. For all REST API operations available for Navigator, the request body supports both plain text MQSC commands and JSON formatted commands.
When executing MQSC commands, the type is runCommand. The response is returned in plain text format.
When executing JSON formatted commands, the type is runCommandJSON. In this case, an MQSC command is built from JSON attributes. The response is returned in JSON format.
To compare MQSC and JSON commands, take the Display command as an example:
DISPLAY QUEUE ('Q1') TYPE(QLOCAL) ALL.
Request
See the IBM online documentation at POST - plain text MQSC command for more information about plain text MQSC commands.
In the request body, use "type": "runCommand". Enter the MQSC command as you would on a command line.
For example:
{
"type": "runCommand",
"parameters": {
"command": " DISPLAY QUEUE ('Q1') TYPE(QLOCAL) ALL "
}
}
The corresponding curl command is provided below:
curl -i -u Admin:admin -X POST "http://192.168.88.233:8019/rest/v1/qmgrs/PC-local/QMGR_Test/mqsc" -H "Content-Type: application/json" -d "{ \"type\": \"runCommand\", \"parameters\": { \"command\": \"DISPLAY QUEUE ('Q1') TYPE(QLOCAL) ALL\" } }"
Response
The response is returned in a plain text format.
HTTP/1.1 201 Created
Date: Mon, 04 Oct 2021 12:25:50 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(9.4.38.v20210224)
{
"overallCompletionCode" : 0,
"overallReasonCode" : 0,
"commandResponse" : [ {
"completionCode" : 0,
"reasonCode" : 0,
"text" : [ "AMQ8409I: Display Queue details.", " QUEUE(Q1)
TYPE(QLOCAL)", " ACCTQ(QMGR) ALTDATE(2021-10-04)", "
ALTTIME(15.08.22) BOQNAME( )", " BOTHRESH(0)
CLUSNL( )", " CLUSTER( ) CLCHNAME( )", " CLWLPRTY(0)
CLWLRANK(0)", " CLWLUSEQ(QMGR) CRDATE(2021-10-04)", "
CRTIME(15.08.22) CURDEPTH(0)", " CUSTOM( )
DEFBIND(OPEN)", " DEFPRTY(0) DEFPSIST(NO)", "
DEFPRESP(SYNC) DEFREADA(NO)", " DEFSOPT(SHARED)
DEFTYPE(PREDEFINED)", " DESCR( ) DISTL(NO)", "
GET(ENABLED) HARDENBO", " IMGRCOVQ(QMGR)
INITQ( )", " IPPROCS(0) MAXDEPTH(5000)", "
MAXMSGL(4194304) MAXFSIZE(DEFAULT)", " MONQ(QMGR)
MSGDLVSQ(PRIORITY)", " NOTRIGGER NPMCLASS(NORMAL)", "
OPPROCS(0) PROCESS( )", " PUT(ENABLED)
PROPCTL(COMPAT)", " QDEPTHHI(80) QDEPTHLO(20)", "
QDPHIEV(DISABLED) QDPLOEV(DISABLED)", " QDPMAXEV(ENABLED)
QSVCIEV(NONE)", " QSVCINT(999999999) RETINTVL(999999999)", "
SCOPE(QMGR) SHARE", " STATQ(QMGR)
STREAMQ( )", " STRMQOS(BESTEF) TRIGDATA( )", " TRIGDPTH(1)
TRIGMPRI(0)", " TRIGTYPE(FIRST) USAGE(NORMAL)" ]
} ]
JSON-formatted command
Request
In the request body, use "type": "runCommandJSON". Enter the MQSC command in a JSON format.
To translate the MQSC command into JSON:
|
Enter this MQSC value |
In this JSON attribute |
Required (Y/N) |
|
primary command keyword Examples: DEFINE, ALTER, DISPLAY, SET |
“command” |
Y |
|
secondary command keyword Examples: QLOCAL, QUEUE, PROCESS, TOPIC |
“qualifier” |
Y |
|
primary argument (for example, name of object) Example: Name of object, or * for All. |
“name” |
N |
|
additional parameters |
“parameters” The name/value pairs in the MQSC command become JSON attributes. This is the list of attributes that need to be retrieved for the command. |
N |
To run this command using the REST API, send the JSON in the body of the POST request to the /rest/v1/qmgrs/PC-local/QMGR_Test/mqsc URL:
{ "type": "runCommandJSON",
"command": "display",
"qualifier": "qlocal",
"name": "Q1",
"parameters": "*"
}
The corresponding curl command is provided below:
curl -i -u Admin:admin -X POST "http://192.168.88.233:8019/rest/v1/qmgrs/PC-local/QMGR_Test/mqsc" -H "Content-Type: application/json" -d "{ \"type\": \"runCommandJSON\", \"command\": \"display\", \"qualifier\": \"queue\", \"name\": \"'Q1'\", \"responseParameters\": [ \"all\" ], \"parameters\": { \"type\": \"qlocal\" } }"
Response
This time, the response is returned in JSON format.
HTTP/1.1 201 Created
Date: Mon, 04 Oct 2021 12:27:56 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(9.4.38.v20210224)
{
"overallCompletionCode" : 0,
"overallReasonCode" : 0,
"commandResponse" : [ {
"completionCode" : 0,
"reasonCode" : 0,
"message" : [ "AMQ8409I: Display Queue details" ],
"parameters" : {
"cluster" : "",
"curdepth" : 0,
"usage" : "NORMAL",
"notrigger" : "YES",
"trigdpth" : 1,
"clchname" : "",
"type" : "QLOCAL",
"put" : "ENABLED",
"qdploev" : "DISABLED",
"defprty" : 0,
"statq" : "QMGR",
"initq" : "",
"qsvciev" : "NONE",
"deftype" : "PREDEFINED",
"streamq" : "",
"clwluseq" : "QMGR",
"msgdlvsq" : "PRIORITY",
"imgrcovq" : "QMGR",
"trigmpri" : 0,
"bothresh" : 0,
"qdphiev" : "DISABLED",
"descr" : "",
"distl" : "NO",
"maxmsgl" : 4194304,
"maxfsize" : "DEFAULT",
"boqname" : "",
"acctq" : "QMGR",
"clwlrank" : 0,
"propctl" : "COMPAT",
"qsvcint" : 999999999,
"trigtype" : "FIRST",
"npmclass" : "NORMAL",
"maxdepth" : 5000,
"altdate" : "2021-10-04",
"hardenbo" : "YES",
"opprocs" : 0,
"crtime" : "15.08.22",
"trigdata" : "",
"alttime" : "15.08.22",
"defbind" : "OPEN",
"monq" : "QMGR",
"get" : "ENABLED",
"scope" : "QMGR",
"qdpmaxev" : "ENABLED",
"share" : "YES",
"clusnl" : "",
"strmqos" : "BESTEF",
"process" : "",
"defpresp" : "SYNC",
"custom" : "",
"clwlprty" : 0,
"defreada" : "NO",
"retintvl" : 999999999,
"crdate" : "2021-10-04",
"ipprocs" : 0,
"defpsist" : "NO",
"qdepthlo" : 20,
"qdepthhi" : 80,
"queue" : "Q1",
"defsopt" : "SHARED"
}
} ]