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
orOperations
authority can deploy an API, users withInvoke
orReader
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
orOperations
authority can set the initial status of an API, users withInvoke
orReader
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