Shared services REST API

Use REST API to complete tasks related to the shared services pattern.

List all shared services

GET /resources/sharedServices/
Table 1. List all shared services.
REST API information Value Description
Example URL https://localhost/resources/sharedServices  
Response content-type application/json  
Response body example 
[
  {
    "last_modifier": "cbadmin",
    "service_type": "",
    "app_name": "ELB Proxy Service",
    "patterntype": "foundation",
    "creator": "cbadmin",
    "service_supported_clients": "[0.0,2.0]",
    "service_version": "2.0",
    "create_time": "2012-04-11T09:51:42Z",
    "last_modified": "2012-04-11T09:51:42Z",
    "access_rights": {
        "cbadmin": "F",
        "_group_:Everyone": "R"
    },
    "service_name": "proxy",
    "version": "2.0",
    "app_type": "service",
    "app_id": "a-2a27189e-03bc-4f49-9526-6e31fdbeb8f7",
    "description": "The ELB Service provides a self managed common service of proxy",
 }，
  ...
]
 
Response code 200 OK
  401 The user is not authorized to perform this action.
  403 Access forbidden
  500 Unexpected error
app_id
The uuid of the shared service.
service_type
type of the shared service. It's "External" or blank
service_name
The name of the shared service, this value won't be translated. Shared services with the same service name can have at most one instance running in one cloud.
app_name
Shared service name. This is translated according to locale.
description
Shared service description, this is translated according to locale.
patterntype
The pattern type's name which the shared service belongs to.
version
The pattern type's version which the shared service belongs to.
last_modifier
The user who last updated the shared service.
last_modified
The time when the shared service was last updated.
app_storehouse_base_url
The shared service's url in storehouse.
creator
The user who created the shared service.
create_time
The creation time of the shared service.
service_supported_clients
Client versions that the shared service can support
service_version
Version of this shared service
access_rights
The object contains all users who have access rights of this shared service.
app_type
The value of all shared services app_type attribute is 'service'

Return a specific shared service

GET /resources/sharedServices/<app_id>
Table 2. Get a list of shared services by application ID
REST API information Value Description
Example URL https://localhost/resources/sharedServices/a-6d29ddbc-7005-469a-878f- b467ff57dd3f  
Response content-type application/json  
Response body example 
{
    "last_modifier": "cbadmin",
    "service_type": "",
    "app_name": "ELB Proxy Service",
    "patterntype": "foundation",
    "creator": "cbadmin",
    "service_supported_clients": "[0.0,2.0]",
    "service_version": "2.0",
    "create_time": "2012-04-11T09:51:42Z",
    "last_modified": "2012-04-11T09:51:42Z",
       "access_rights": {
        "cbadmin": "F",
        "_group_:Everyone": "R"
    },
    "service_name": "proxy",
    "version": "2.0",
    "app_type": "service",
    "app_id": "a-2a27189e-03bc-4f49-9526-6e31fdbeb8f7",
    "description": "The ELB Service provides a self managed common service of proxy"
}
  
Response code 201 OK
  400 Invalid request parameter.
  401 The user is not authorized to perform this action.
  409 Instance exists in the cloud.
  500 Unexpected error

Create a shared service with specific attributes

POST /resources/sharedServices/
Different kinds of attributes can be combined. A unique ID is generated for the shared service.
Table 3. Create a shared service with specific attributes
REST API information Value Description
Example URL https://localhost/resources/sharedServices/  
Request body

Content-type

 Content-Type - application/json (appmodel json file)

Content-Type - application/zip file (compressed file that includes the application model and artifacts files)

  
Request body example JSON Application model  
Response content-type application/json  
Response example 
{
   "content_type": "application/json",
   "last_modifier": "tester",
   "create_time": "2011-02-24T05:41:34Z",
   "last_modified": "2011-02-24T05:41:34Z",
   "access_rights": {
      "tester": "F"
   },
   "content_md5": "EF7142254CD653D987E9A9E8A48C01D3",
   "app_type": "application",
   "app_id": "a-4e21f6e9-2ca7-4a3a-a5cc-00f04f7b7f08",
   "app_name": "test",
   "creator": "tester"
}
  
Response header location https://localhost/resources/sharedServices/a-4e21f6e9-2ca7-4a3a-a5cc-00f04f7b7f08  
Response code 201 Created
  401 The user is not authorized to perform this action.
  403 Access forbidden
  412 Invalid parameter supplied, for example, the JSON file is invalid.
  415 Invalid content type
  500 Unexpected error

Deploy a shared service

There are two options when you deploy a shared service:
  1. Deploy the shared service with the placement that is determined by the system, if applicable, or by not using placement if it is not supported by the shared service. To deploy the shared service with this method, use the POST REST API and do not include the placement_only parameter in the request body, or set it to False.
  2. Modify the placement before you deploy the shared service, and use the modified placement for the deployment. To use this method, the deployment must be called in two phases:
    • First, generate the placement and topology by including placement_only:"True" in the request body.

      This parameter tells the system to generate a placement for the deployment, which is returned in response body. You can modify this placement before you pass it to the system in the second phase to deploy the shared service.

    • Then, deploy the shared service by calling the PUT REST API with the deployPlacement operation, and pass the modified placement for the deployment in the request body.
Notes:
  • Because placement is handled by the system, you do not have to specify a cloud group or IP group if an environment profile is specified. If the pattern cannot use placement, then the cloud group and IP group parameters are required. For example, if some of the plug-ins in the pattern do not require Foundation 2.1, the application cannot use placement. In this scenario, the cloud group and IP group are required. If you do not specify these parameters for a pattern that cannot use placement, the deployment fails.
  • If "placement_only":True is in the request body, but placement is not supported for the pattern, that parameter is ignored by the system. The pattern is deployed as if the placement_only was not specified, or was set to False.
Restriction: If your API version is less than 5.0.0.0:
  • The cloud group and IP group are required parameters.
  • Deploying to an environment profile with the cloud management type set to "By way of external network" is not supported.
Deploy the shared service or generate the placement if you are using the two-phase method:
POST /resources/sharedServices/<app_id>/sharedServiceInstances
Table 4. Deploy a shared service.
REST API information Value Description
Example URL https://localhost/resources/sharedServices/a-6d29ddbc-7005-469a-878 f-b467ff57dd3f/sharedServiceInstances  
Response content-type application/json  
Response body example Same as the response body of REST API Virtual application patterns REST API  
Response code 201 OK
  400 Invalid request parameter.
  401 The user is not authorized to perform this action.
  409 Instance exists in the cloud.
  412 This code is returned if a precondition failed.
  500 Unexpected error
Note: The supported attributes are the same as the response body of REST API Virtual application patterns REST API.
Second phase of a two-phase deployment:
PUT /resources/sharedServiceInstances/instance_id
You can specify this parameter in the request body:
placement
Required. The modified placement for the deployment.
Table 5. Deploy a shared service- second phase with modified placement
REST API information Value Description
Example URL https://localhost/resources/sharedServiceInstances/d-55e08a31-a3f0-419e-b262-3cdba2cf6be2  
Request content-type application/json

Specify the updated placement in the request body.

  
Request example 
{
    "operation": "deployPlacement",
    "topology_parameters"： {},
    "addon_parameters": {},
    "placement": { //required
        "vm-templates": [{
            "locations": [{
                "name": "1721665121",
                "cloud_groups": [{
                    "name": "esxset15",
                    "instances": [{
                        "new_instances": 1,
                        "nics": [{
                            "ip_groups": [{
                                "name": "172",
                                "new_instances": 1,
                                "purpose": "data"
                            }],
                            "name": "management",
                            "purpose": "data"
                        }]
                    }]
                }],
                "new_instances": 1
            },
            {
                "name": "1721665123",
                "cloud_groups": [{
                    "name": "esxset16",
                    "instances": [{
                        "new_instances": 1,
                        "nics": [{
                            "ip_groups": [{
                                "name": "172_2",
                                "purpose": "data",
                                "new_instances": 1
                            }],
                            "name": "management",
                            "purpose": "data"
                        }]
                    }]
                }],
                "messages": ["CWZKS6401E: 1721665123 is missing image IBM OS Image for Red Hat Linux Systems:2.1.0.0."],
                "new_instances": 1
            }],
            "environment_profile": "MyTest",
            "name": "Web_Application-was",
            "new_instances": 2
        }],
        "version": "5.0.0.0"
    }
}
  
Response code 200 OK
  401 The user is not authorized to perform this action.
  403 Access forbidden
  404 The application that is specified by {appID} is not found.
  412 A specified parameter is not valid. For example, the JSON file is not valid.
  500 Unexpected error

Update a shared service

PUT /resources/sharedServices/{app_id}
Table 6. Update a shared service
REST API information Value Description
Example URL https://localhost/resources/sharedServices/a-cdaac959-672c-4df7-a648-b333a3843422  
Request content-type and body Content-Type - application/json (body is the application model JSON file)

Content-Type - application/zip (body is compressed file, including the application model and artifacts files)

  
Request content-type application/json  
Response body example 
{
   "content_type": "application/json",
   "last_modifier": "tester",
   "create_time": "2011-02-24T05:41:34Z",
   "last_modified": "2011-02-24T05:41:34Z",
   "access_rights": {
      "tester": "F"
   },
   "content_md5": "5B8F7E6CF56F7CE804788C0086589AFF",
   "app_type": "application",
   "app_id": "a-fb70796e-1b13-467a-babe-b8b700bd563b",
   "name": "App for Testing",
   "locked": "false",
	"creator": "tester"
}
  
Response code 200 OK
  401 The user is not authorized to perform this action.
  403 Access forbidden
  404 The application that is specified by {appID} is not found.
  412 A specified parameter is not valid. For example, the JSON file is not valid.
  500 Unexpected error

Delete a specified shared service

DELETE /resources/sharedServices/{app_id}
Table 7. Delete a specified shared service
REST API information Value Description
Example URL https://localhost/resources/sharedServices/a-cdaac959-672c-4df7-a648-b333a3843422  
Response content-type application/json  
Response code 200 OK
Note: If an application specified by {appID} is not found, the 200 response code returns, response body: {"success": "false"})
  401 The user is not authorized to perform this action.
  403 Access forbidden
  409 Conflict
  500 Unexpected error