REST is an architectural pattern for implementing web-based access to resources on top of HTTP. REST stands for REpresentational State Transfer and is the way the web works today. URI are used to specify resources that can be acted upon using the HTTP verbs GET, PUT, POST, and DELETE. So if you send an HTTP DELETE request to the endpoint /books/OfMiceAndMen, this would indicate that you want to delete the book "Of Mice And Men."

More information about REST can be found on Wikipedia ({+}http://en.wikipedia.org/wiki/Representational_state_transfer+) and elsewhere on the web.

Introduction to JSON

JSON is a human readable, text-based, data interchange format that is ideally suited for web servers and their browsers, but can also be used as a general data interchange format much in the same vein as XML is used as a data interchange format. JSON is language independent and there are many libraries that can be used to create and consume JSON data.

JSON objects are key/value pairs delimited by {}. The keys are specified as string data types and the values can be numbers, strings, arrays, or objects. Here is an example:

{
   "items":[
      {
         "name":"Developers",
         "description":"Developers default description.",
         "connections":[
            {
               "namespace":"wmq",
               "name":"QUICKSILVER",
               "filters":[
                  {
                     "name":"NotSystemQueues",
                     "namespace":"wmq"
                  }
               ]
            }
      }
   ],
   "identifier":"name",
   "label":"name",
   "rc":200,
   "msg":"Data retrieved successfully"
}

This particular object is part of a TrueSight Middleware Administrator project definition. Note that the project is returned in an array named "items". The project object begins with the character '{', has a "name" field with the value "Developers" and has a list of connections associated with the project in the "connections" array. More information about JSON can be found at ({+}http://json.org+/).

REST in TrueSight Middleware Administrator

TrueSight Middleware Administrator follows the REST architecture as closely as possible. TrueSight Middleware Administrator attempts to make URI's used to access resources as intuitive as possible. The data format used in responses is always JSON.

A URI in TrueSight Middleware Administrator is an HTTP URL, so it includes the scheme 'http', and the host and port that identify the TrueSight Middleware Administrator service on which the resources reside.

After the port, the endpoint begins with the text 'bmmadmin'. Following 'bmmadmin', a namespace must be specified. The currently accepted namespaces are 'admin', 'wmq', and 'ems'. The resource being accessed will define what namespace must be used to access that resource. For instance, if you want to access WebSphere MQ queues, the namespace you would use is 'wmq'. If you want to access TrueSight Middleware Administrator resources such as projects, users, groups, connection definitions, etc., you use the namespace 'admin'.

After the namespace, the components in the URI vary depending on the resources being accessed.

Here is an example of a TrueSight Middleware Administrator URI that would be used to access projects defined within a particular TrueSight Middleware Administrator service:
https://quicksilver.bmc.com:8443/bmmadmin/admin/projects

Invoking this URL with a GET HTTP verb would get you an array of all defined projects on that TrueSight Middleware Administrator server instance.

Here is an example URI that identifies an individual project:
https://quicksilver.bmc.com:8443/bmmadmin/admin/projects/Developers

Invoking this URL with a GET HTTP verb would get you the specific properties for the project named "Developers". Note how ".../projects/" is used as a "collection" of an object type (in this case, projects).

This is common in REST APIs: to get a listing of a set of resources, you GET the collection. To get a particular resource, you GET the identifier of the resource at the collection. To create a new resource, you POST to the collection, to modify an existing resource, you PUT to a particular resource in the collection, to delete an existing resource you DELETE a particular resource in the collection. The HTTP verbs are used to perform CRUD (create, read, update, delete) operations against sets of resources and individual resources.

The TrueSight Middleware Administrator REST API works exactly like this. A user of the REST API needs to know how to identify a resource (the URL), specify an operation to be done to the resource (GET, POST, PUT, DELETE), and understand the data format to be sent or received as part of the specific operation (JSON data format).

Return Values

In the REST API, the return values are always represented by a JSON object that contains an "rc" field, a "msg" field and an "items" field. Generally, an rc value of 1 means success and anything else is intended to be an error. Depending on the namespace, the error code might be specific to the middleware environment (e.g. you would see a 2085 rc if you asked for the properties of a WebSphere MQ object that doesn't exist).

In this guide, note that the "returns" sections document what is returned in the "items" field. So when it says "None" for "Returns", the REST API does get the "rc" and "msg" fields, but the "items" array is empty.

Getting Started

To get started exploring the RESTful API, a command-line program called "cURL" ({+}http://curl.haxx.se+/) can be used to interact with the TrueSight Middleware Administrator service. cURL is a very sophisticated open-source HTTP client that can be used to interact with HTTP servers.

Before getting any information back from a TrueSight Middleware Administrator service, you must have the following:

• A valid product key
• A valid username and password
• A username that has been assigned to at least one project or an administrative user
• If accessing administrative objects, like projects, connections, users, groups, etc. you must have Product Administrative rights (your username must be in the "Administrators List" in the TrueSight Middleware Administrator admin console)

Note that the responses in the examples below have been formatted for readability. It can be helpful when working with the scripting API to format responses. A tool like the one at {+}http://jsonformatter.curiousconcept.com+/ can be very helpful.

Logging In

curl --insecure -c cookies.txt -d "j_username=admin&j_password=admin" https://quicksilver.bmc.com:8443/bmmadmin/j_spring_security_check

Getting All Projects

curl --insecure -b cookies.txt --header "Content-Type:application/json" https://quicksilver.bmc.com:8443/bmmadmin/admin/projects

The response to this curl invocation is a summary of all the projects that have been created:

{
   "items":[
      {
         "name":"Developers",
         "description":"Developers default description."
      },
      {
         "name":"Production",
         "description":"Production default description."
      }
   ],
   "identifier":"name",
   "label":"name",
   "rc":200,
   "msg":"Data retrieved successfully"
}

Getting a Project

curl --insecure -b cookies.txt --header "Content-Type:application/json" https://quicksilver.bmc.com:8443/bmmadmin/admin/projects/Developers

The response:

{
  "items":[
    {
      "name":"Developers",
      "description":"Developers default description",
      "FileAccessEnabled":true,
      "connections":[
        {
          "namespace":"wmq",
          "name":"QM_BMC4TGTG5J",
          "filters":[
            {
              "name":"WF_WMQ_Q_A",
              "namespace":"wmq"
            }
          ],
          "pfilters":[
            {
              "name":"PF_Dev_Inquire",
              "namespace":"wmq"
            }
          ]
        }
      ],
      "users":[
        {
          "user":"admin",
          "permissions":["READ","DELETE","ADMINISTRATION","OPERATOR","INQUIRE","WRITE"]
        }
      ],
      "groups":[
        {
          "group":"Developers",
          "permissions":["READ","DELETE","INQUIRE","WRITE"]
        }
      ],
      "links":[
        {
          "name":"WMQ 7.1 Info Center",
          "url":"http:\/\/www-01.ibm.com\/support\/knowledgecenter\/SSFKSJ_7.1.0\/com.ibm.mq.doc\/mq50090_.htm"
        },
        {
          "name":"Google",
          "url":"http:\/\/www.google.com"
        }
      ]
    }
  ],
  "identifier":"name",
  "label":"name",
  "rc":200,
  "msg":"Data retrieved successfully"
}

Creating a Project

curl --insecure -b cookies.txt --header "Content-Type:application/json" -d "{\"name\":\"Test\", \"description\":\"A New Test Project\"}" https://quicksilver.bmc.com:8443/bmmadmin/admin/projects/

If successful, the following is the response:
{"rc":1,"msg":"The operation succeeded."}

Modifying a Project

curl --insecure -b cookies.txt --header "Content-Type:application/json" -X PUT -d "{\"name\":\"Test\", \"description\":\"A Test Project\", \"users\":[{\"user\":\"cching\", \"permissions\":[\"INQUIRE\",\"READ\",\"DELETE\",\"WRITE\",\"OPERATOR\",\"ADMINISTRATION\"]}]}" https://quicksilver.bmc.com:8443/bmmadmin/admin/projects/Test

If successful, the following is the response:
{"rc":1,"msg":"The operation succeeded."}

Deleting a Project

curl --insecure -b cookies.txt --header "Content-Type:application/json" -X DELETE https://quicksilver.bmc.com:8443/bmmadmin/admin/projects/Test

If successful, the following is the response:
{"rc":1,"msg":"The operation succeeded."}