Maintenance API for Avaya Session Border Controller for Enterprise (Release 10.2.1.0 / Spec Revision 1.0)

Download OpenAPI specification:Download

This is the Maintenance API definition for the Avaya Session Border Controller for Enterprise.

Each supported endpoint is defined in this file along with a description of the endpoint, any required parameters, permissions, and the expected responses with examples. Detailed information on how to fully configure a system from start to finish can be found in the Administering Avaya Session Border Controller for Enterprise document available on the Avaya Support site (see https://support.avaya.com/products/P0997/avaya-session-border-controller-for-enterprise/).

Note that each endpoint definition also includes an embedded x-required-capability property which contains the required permissions for the endpoint (this is also included in the description).

Upgrade

Preparation for Upgrade

Copy Files: Copy the upgrade package file and the signature file (.asc) to the folder located at /archive/urpackages.

Start Upgrade: Once the files are copied, start the upgrade process using the API.

Track the Upgrade Process

Device upgrades are managed through an API that tracks the status of the upgrade process. The process transitions through several states based on API calls and events triggered during the upgrade:

Upgrade Process States

  1. INITIATED: This is the initial state when the upgrade process is started via the API.

  2. STARTING: After initiation, the upgrade moves to the starting phase, where initial setup and checks are performed.

  3. IN_PROGRESS: Once the starting phase is complete, the upgrade progresses to the in-progress state. During this phase, actual updates and changes to the device or system are made. This state includes activities such as down the services, installing updates and start the services.

  4. REBOOTING: The upgrade process requires a reboot to apply the changes, thus transitioning the process to the reboot state.

  5. COMPLETED: In a successful scenario, the upgrade process reaches the completed state, indicating that all phases of the upgrade, including any necessary reboots, have been successfully executed.

  6. FAILED: If an error occurs at any stage of the upgrade process, the upgrade can transition to the failed state. This could happen due to various reasons during update execution.

Tracking Upgrade Status

The status of the upgrade process can be monitored and tracked using the upgrade status API. This API allows consumers to retrieve the current state of the upgrade, providing insights into whether the process is in progress, completed successfully, or has encountered any issues.

Handling Status Codes

  • During the IN_PROGRESS state, which involves actively updating and modifying services, both the Upgrade status API and authentication API may return various HTTP status codes such as 500, 502, 504, or 401. These codes represent different scenarios, such as server errors (500), bad gateway errors (502), gateway timeouts (504), or unauthorized access (401). To handle these situations effectively, API consumers should implement robust error handling mechanisms. This includes implementing retry strategies for transient errors (500, 502, 504) and ensuring proper management of authentication and authorization issues (401).

  • In contrast, while in the REBOOTING state, the upgrade status API service will be unavailable. The upgrade process will transition to COMPLETED once the device successfully completes the reboot process.

Note: The upgrade process can take upto 40 minutes, depending on the system specifications.

Upgrade Process Flow chart

Upgrade Api Framework image

Upgrade Process API framework Sequence chart

Upgrade Api Framework image

Start Upgrade

Start an upgrade on this device.

This API endpoint will return immediately upon successfully starting the upgrade process. Further inquiries must be made to the API via the status and logs endpoints to check the status of the upgrade after it has started.

User must have the upgrade:update capability to perform this action.

Responses

Response samples

Content type
application/json
{
  • "status": "INITIATED",
  • "code": "INITIATED",
  • "message": "Upgrade process initiated successfully.",
  • "details": {
    }
}

Get Upgrade Status

Get the current upgrade status.

This API endpoint will return the current upgrade status associated with the provided transaction-id. This value will be returned after an upgrade has been started and must be used get the correct upgrade status.

Note: The recommended interval between Upgrade status API calls is 5 to 10 seconds.

User must have the upgrade:read capability to perform this action.

path Parameters
transaction-id
required
string

transaction-id to track the upgrade status. This is must be required to get the status. This value provided as part of Upgrade initialization service call response.

Responses

Response samples

Content type
application/json
{
  • "status": "FAILED"
}

Get Upgrade Logs

Get the logs generated while upgrading the system.

This API endpoint returns the current upgrade logs associated with the provided transaction-id. This value is generated once an upgrade has started and must be used to fetch the correct upgrade logs.

User must have the upgrade:read capability to perform this action.

Responses

Response samples

Content type
application/json
{
  • "status": "LOGS_FOUND",
  • "message": "Logs found",
  • "details": {
    }
}

Hotfix

Preparation for Hotfix installation

Copy Files: Copy the hotfix package file and the signature file (.md5) to the folder located at /home/ipcs.

Start Hotfix installation: Once the files are copied, start the hotfix installation using the API.

The hotfix installation is involved with various states as described below:

Hotfix Install States.

  1. STARTING
  • Indicates that the hotfix installation process has begun. This is the initial state where preliminary checks and preparations are being made.
  1. EXTRACTING
  • The system is extracting the contents of the hotfix package. This involves decompressing the files and preparing them for installation.
  1. INSTALLING
  • The extracted files are being installed onto the system. This includes copying files, applying patches, and making necessary system modifications.
  1. INSTALLED
  • The installation of the hotfix has been successfully completed. All files and patches have been applied, and the system is updated with the new hotfix.
  1. REBOOTING
  • The system is undergoing a reboot to apply the changes made by the hotfix. Some updates require a restart to take effect fully.
  1. COMPLETED
  • The entire hotfix installation process has been successfully finished, including any required reboots. The system is now running with the applied hotfix.
  1. INVALID_HOTFIX
  • The provided hotfix is not valid. This could be due to corruption, incompatibility, or incorrect formatting of the hotfix package.
  1. ALREADY_INSTALLED
  • The hotfix has already been installed on the system. No further action is needed as the system is already up to date with this specific hotfix.
  1. INVALID_TARBALL
  • The tarball (compressed package file) provided for the hotfix is invalid. This could be due to corruption, incorrect file format, or issues during download.
  1. FAILED
  • The hotfix installation process has failed. This state indicates that an error occurred during one of the previous stages, preventing the hotfix from being applied successfully.
  1. PRECHECK_FAILED
  • The hotfix installation process has failed at pre check. This could be caused by disk space issue or the issue with system current sate or md5 validation issue.

Tracking Hotfix installation Status

The status of the hotfix install process can be monitored and tracked using the hotfix install status API. This API allows consumers to retrieve the current state of the hotfix install, providing insights into whether the process is in progress, completed successfully, or has encountered any issues.

Handling Status Codes

  • During the INSTALLING state, which involves actively updating and modifying services, both the Hotfix install status API and Authentication API may return various HTTP status codes such as 500, 502, 504, or 401. These codes represent different scenarios, such as server errors (500), bad gateway errors (502), gateway timeouts (504), or unauthorized access (401). To handle these situations effectively, API consumers should implement robust error handling mechanisms. This includes implementing retry strategies for transient errors (500, 502, 504) and ensuring proper management of authentication and authorization issues (401).

  • In contrast, while in the REBOOTING state, the hotfix install status API service will be unavailable. The hotfix install status will transition to COMPLETED once the device successfully completes the reboot process.

Note: The hotfix installation can take upto 30 minutes, depending on the system specifications.

Start Hotfix Installation

Start a hotfix installation on this device.

This API endpoint will return immediately upon successfully starting the hotfix installation process. Further inquiries must be made to the API via the status and logs endpoints to check the status of the hotfix installation after it has started.

User must have the hotfix:install capability to perform this action.

Request Body schema: application/json

Hotfix information that need to be installed.

hotfix-file-name
string

Responses

Request samples

Content type
application/json
{
  • "hotfix-file-name": "asbc-10.2.0.1-Hotfix-001-24395.tgz"
}

Response samples

Content type
application/json
{
  • "status": "STARTING",
  • "code": "STARTING",
  • "message": "Hotfix install process initiated successfully.",
  • "details": {
    }
}

Get Hotfix Status

Get the current hotfix installation status.

This API endpoint will return the current hotfix installation status associated with the provided transaction-id. This value will be returned after a hotfix installation has been started and must be used get the correct hotfix installation status.

User must have the hotfix:read capability to perform this action.

Note: The recommended interval between Hotfix status API calls is 5 to 10 seconds.

path Parameters
transaction-id
required
string

transaction-id to track the hotfix install status. This is must be required to get the status. This value provided as part of hotfix install initialization service call response.

Responses

Response samples

Content type
application/json
{
  • "status": "STARTING"
}

Get Hotfix Logs

Get the current hotfix installation status.

This API endpoint will return the current hotfix installation status associated with the provided transaction-id. This value will be returned after a hotfix installation has been started and must be used get the correct hotfix installation status.

User must have the hotfix:read capability to perform this action.

Responses

Response samples

Content type
application/json
{
  • "status": "LOGS_FOUND",
  • "message": "Logs found",
  • "details": {
    }
}