Creating configurations by using REST

You can create a new configuration by using the REST management interface.

Compose the valid request payload

To create an object configuration, create a valid payload that contains the new configuration. To begin constructing the payload, identify the structural description of the target object, that is, the object schema. You can retrieve a schema from the metadata resource of the REST management interface by using a request of the following form:
GET https://mqhost.com:5554/mgmt/metadata/default/object_name

Where object_name identifies the configuration object that you want to create. For example, to retrieve the metadata resource for the host alias configuration object, you would make the following request:

GET https://mqhost.com:5554/mgmt/metadata/default/HostAlias
You receive the following response:
{
        "_links" : {
           "self" : {
               "href" : "/mgmt/metadata/default/HostAlias"
           }, 
           "doc" : {  
               "href" : "/mgmt/docs/metadata/HostAlias"
           }
        }, 
        "object" : {
           "name" : "HostAlias", 
           "uri" : "network/host-alias", 
           "cli-alias" : "host-alias", 
           ...
           "properties" : {
               "property" : [{
                 "name" : "mAdminState", 
                 "type" : {
                    "href" : "/mgmt/types/default/dmAdminState"
                 }, 
                 "cli-alias" : "admin-state", 
                 "default" : "enabled", 
                 ...
                 }, 
                 {
                 "name" : "UserSummary", 
                 "type" : {
                     "href" : "/mgmt/types/default/dmString"
                 }, 
                 "cli-alias" : "summary", 
                 "display" : "Comments", 
                 ... 
                 }, 
                 {
                 "name" : "IPAddress", 
                 "type" : {
                     "href" : "/mgmt/types/default/dmIPHostAddress"       
                  }, 
                  "required" : "true", 
                  "cli-alias" : "ip-address", 
                  "display" : "IP address", 
                  ...
                 }
               ]}
            }
}

You can also acquire the metadata for the object that you want to create by looking up the appliance Service-Oriented Management Interface (SOMA) schema for the configuration object. The SOMA schemas are located in the store:///xml-mgmt.xsd file.

From the resource metadata, you can identify the properties that are required to create the target object. You can also identify the property names to use in the payload. By using this information, you can create a proper JSON request payload. A JSON payload has the following structure:
{
  "object_class_name": {
    "name": "object_name",
    "property1_name": "property1_value",
    "property2_name": "property2_value",
    "property3_name": "property3_value",
    "property4_name": "property4_value"
    ...
  }
}
Using the information that you retrieved about the host alias configuration object, you could create the following payload:
{
  "HostAlias": {
    "name": "Key_server",
    "UserSummary": "Alias for Keysoe server",
    "IPAddress": "198.51.100.30",
  }
}

Compose the valid request URI

You can choose from two approaches to create a configuration object. Both approaches achieve the same result, but target a different URI. The first approach uses an HTTP POST request, and the second uses an HTTP PUT request. Use the POST request to create objects because a POST request results in failure if an object with the same name exists in the target domain. This approach prevents you from accidentally overwriting an existing object configuration. However, you can create an object configuration by using a PUT request. Issuing a PUT request on an existing object configuration overwrites the configuration with the values in the request payload.

The following POST request could be used to create the host alias object that is defined by the example payload:
POST https://mqhost.com:5554/mgmt/config/default/HostAlias
The following PUT request could also be used to create the host alias object that is defined by the example payload:
PUT https://mqhost.com:5554/mgmt/config/default/HostAlias/Key_server
When you send the request, both the POST and PUT requests return the same response after the object is successfully created:
{
  "result": "",
  "_links": {
    "self": {
      "href": "/mgmt/config/default/HostAlias"
    },
    "doc": {
      "href": "/mgmt/docs/config/HostAlias"
    }
  },
  "Key_server": "Configuration has been created."
}

Note that, if you repeat the POST request with the same payload, the command will fail. If you repeat the PUT request, the command will succeed.