Deploy a service

Use the HTTP method POST to deploy your service to make it available for use.

zosConnect-2.0 Applies to zosConnect-2.0.

HTTP method
POST
URI
/zosConnect/services

If the service name contains forward slashes, they must be escaped by using %2F. For example, if the service name is MyService/v1, it must be provided as MyService%2Fv1.

Note: Added in V1.1.0 of the administration interface.
Description
Deploys a service into IBM® z/OS® Connect.
Security
Users with Admin or Operations authority can deploy a service, users with Invoke or Reader authority cannot. For more information about user authorization, see Overview of IBM z/OS Connect security.
Note: A user must be a member of a global group to be able to deploy a service.
Request body
The service archive file. The Content-Type for the request is application/zip.
Response body
Note: The enhanced administration interface V1.2.0 includes version information for services in the response body.
{
    "zosConnect": {
        "serviceName": "<service name>",
        "serviceDescription": "<service description>",
        "serviceProvider": "<service provider>",
        “version”: “<version>”,
        "serviceURL": "<service URL>",
        "serviceInvokeURL": "<service invocation URL>",
        "dataXformProvider": "<data transformation provider>",
        "serviceStatus": "<service status>"
    },
    "<service name>": {
        .. <service provider-specific information>
    }
    }
}
Example response body
{
    "zosConnect": {
        "serviceName": "patient",
        "serviceDescription": "Patient lookup service",
        "serviceProvider": "imsmobile-2.0",
        “version”: “1.1.0”
        "ServiceURL": "https://server1.mycom.com:53633/zosConnect/services/patientService",
        "serviceInvokeURL": "https://server1.mycom.com:53633/zosConnect/services/patientService?action=invoke",
        "dataXformProvider": "DATA_UNAVAILABLE",
        "serviceStatus": "Started"
    },
    "patient": {
        "imsServiceType": "ims-sar",
        "serviceDescription": "Patient lookup service",
        "id": "patient",
        "tranCode": "IVTNO",
        "serviceProviderName": "imsmobile-2.0",
        "status": "Started"
    }
}
Errors
The following errors can occur:
400 Bad request
Invalid or missing service archive file

409 Conflict
z/OS Connect service install failed. The service name {service name} is already in use.

415 Unsupported media type
An unsupported media type of application/json was specified under request URL {service URL}.

500 Internal Server Error
Server issue, might require administrator intervention.

503 Service unavailable

A 503 error could mean that the service provider that is specified in the service archive is not available on the server, or the zosconnect_services element in not present in the server.xml configuration file.

Setting the initial status of a new service

When you deploy a new service, the default initial status is set to Started. You can optionally set the initial status to Stopped by appending a query string to the HTTP POST method:

HTTP method
POST
URI
/zosConnect/services?status=stopped
Description
Deploys a new service into IBM z/OS Connect and sets the status to Stopped. When a service is stopped, requests invoking the service will fail. Administration requests to /zosConnect/services/{serviceName} will still function as normal and the service will appear in the list returned by a GET request to /zosConnect/services. To start the service after it has been deployed, see Change the status of a service.
Note: The enhanced administration interface V1.2.0 includes version information for services in the response body.
Security
Users with Admin or Operations authority can set the initial status of an API, users with Invoke or Reader authority cannot. For more information about user authorization, see Overview of IBM z/OS Connect security.
Request body
Service archive file to be deployed.
Example request

To deploy a service and set the initial status to stopped:

/zosConnect/services?status=stopped
Response body
{
    "zosConnect": {
        "serviceName": "<service name>",
        "serviceDescription": "<service description>",
        "serviceProvider": "<service provider>",
        “version”: “1.1.0”
        "serviceURL": "<service URL>",
        "serviceInvokeURL": "<service invocation URL>",
        "dataXformProvider": "<data transformation provider>",
        "serviceStatus": "<service status>"
    },
    "<service name>": {
        "imsServiceType": "<service type>",
        "serviceDescription": "<service description>",
        "id": "<service ID>",
        "tranCode": "<IMS transaction code invoked by the service if service provider is IMS>",
        "serviceProviderName": "<service provider>",
        "status": "<service status>"
    }
    }
}
Errors
The following error can occur:
400 Bad request
Unknown status specified