Change the status of an API

A query string option can be used to set the status of an API. If the API archive file, is not usable, the operation fails.

Note: When an API is stopped, the API will not invoke interceptors for new requests, and returns the following message:

   503 Service Unavailable

The error response body contains:

   { "errorMessage": "The API has been stopped" }

Note: The status of an API can be either started, or stopped. You can change the status with the HTTP PUT method.

HTTP method

PUT

URI

/zosConnect/apis/{apiName}?status=started|stopped

Description

Starts or stops the existing API. When an API is stopped, new requests fail but existing requests will run to completion. Administration requests to /zosConnect/apis/{apiName} still function normally and the API appears in the list that is returned by the /zosConnect/apis request.

Security

Users with Admin or Operations authority can change the 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

To change the status of an API, the request body should have no content. If an API archive file is in the request body, the request is to update the API and set the initial status after the update. For more information, see Update an API.

Example request

To change the status of the API called apiName to started:

/zosConnect/apis/apiName?status=started

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"
  }
}

Note: Responses from GET requests, such as GET /zosConnect/apis/{apiName}?status=started, include the status property. For example:

{
  "name": "API name",
  "version": "version",
  "description": "API description",
  "status": "Started|Stopped",
  "apiUrl": "API base path",
  "documentation": {
    "swagger": "API Swagger document location"
    }
  }

Errors

400 Bad request
Unknown status specified