Deploying an API

You must deploy your API to make it available for use.

You can use the HTTP method POST to deploy a IBM® z/OS® Connect API.

HTTP method
POST
URI
/zosConnect/apis
Description
Deploys an API into IBM z/OS Connect. The server will store the API in a file using the API name as the filename and a file extension of .aar.
Security
Users with Admin or Operations authority can deploy an API, 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 an API.
Request body
The API archive file file. The Content-Type for the request is application/zip.
Response body
{
  "name": "{name}",
  "version": "{version}",
  "description": "{API description}",
  "status": "{Started|Stopped}",
  "apiUrl": "http(s)://{host}:{port}/{basePath}",
  "documentation": {
    "swagger":"http(s)://{host}:{port}/{basePath}/api-docs"
  }
}
Example response body

 {   
    "name": "testHealthApi2",
    "version": "1.0.0"
    "description": "Health API",
    "status": "Started",
    "apiUrl": "http://192.168.99.100:9080/testHealthApi2",
    "documentation": {
       "swagger": "http://192.168.99.100:9080/testHealthApi2/api-docs"
     }
 }
Errors
The following errors can occur:
400 Bad request
Invalid or missing API archive file

409 Conflict
Package conflicts with the existing z/OS Connect configuration

415 Unsupported media type
Content-Type is not application/zip

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

Setting the initial status of a new API

When you deploy a new API, 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/apis?status=stopped
Description
Deploys a new API into IBM z/OS Connect and sets the status to Stopped. When an API is stopped, requests invoking the API will fail. Administration requests to /zosConnect/apis/{apiName} will still function as normal and the API will appear in the list returned by a GET request to /zosConnect/apis. To start the API after it has been deployed, see Change the status of an API
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
API archive file to be deployed.
Example request

To deploy an API and set the initial status to stopped:

/zosConnect/apis?status=stopped
Response body
{
  "name": "{name}",
  "version": "{version}",
  "description": "{API description}",
  "status": "{Started|Stopped}",
  "apiUrl": "http(s)://{host}:{port}/{basePath}"
  "documentation": {
    "swagger":"http(s)://{host}:{port}/{basePath}/api-docs"
  }
}
Errors
The following error can occur:
400 Bad request
Unknown status specified