Introduction

With the IBM Cloud® Platform Notifications API, you can view notifications, manage last viewed notifications and manage notification distribution lists and preferences for your IBM Cloud accounts. Use the RESTful API to interact with destination entries, notification, and communication preferences. Configured destinations receive platform notifications about incidents, maintenance updates, and other important account-level communications.

The Distribution list API currently supports adding only IBM Cloud Event Notifications destinations. For more information on using Event Notifications with platform notifications, see Enabling Event Notifications for the notification distribution list and Getting started with Event Notifications.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>platform-notifications</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:platform-notifications:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/platformnotificationsv1"
)

go get -u github.com/IBM/platform-services-go-sdk/platformnotificationsv1

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The Platform Notifications API uses the following global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://notifications.cloud.ibm.com/api

Example API request

curl --request GET \
--header "content-type: application/json" \
--header "accept: application/json" \
--header "authorization: Bearer <IAM_token>" \
--url "https://notifications.cloud.ibm.com/api/v1/distribution_lists/<account_id>/destinations"

Replace <IAM_token> and <account_id> in this example with your IAM token value and account ID for your particular API call.

Authentication

The IBM Cloud Platform Notifications API uses Identity and Access Management (IAM) to authenticate requests. Authorization is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <IAM_token>'.

To call each method, you must be assigned a role that includes the required IAM actions. Each method lists the associated IAM action and the service that the action must come from.

For querying destinations, you need Viewer role or higher for Platform Notifications service. For editing destinations, you need Editor role or higher for Platform Notifications service, and you also need Viewer role or higher for the Event Notifications service to add Event Notifications destinations. Note that the Platform Notifications service is part of the All Account Management services, therefore the appropriate role on All Account Management services is also sufficient.

You can add an Event Notifications instance of an account as a destination in another account's distribution list, granted that the two accounts are part of the same enterprise. To do this, you need to be assigned the appropriate roles in both accounts. For more information, see the Managing your enterprise documentation.

Retrieve your access token as shown in the following sample request:

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Error handling

The Platform Notifications API uses standard HTTP response codes to indicate whether a method was completed successfully. A 2xx response indicates success. A 4xx type response indicates a failure, and a 5xx type response indicates an internal system error.

| HTTP Error Code | Description | Recovery | |-----------------|-------------|----------| | 200 | Success | The request was successful. | | 201 | Created | The resource was successfully created. | | 204 | No Content | The request was successful. No response body is provided. | | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all the required parameters in your request. This error can also occur when the maximum limit of 10 destinations per destination type has been reached. | | 401 | Unauthorized | You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again. | | 403 | Forbidden | The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions. | | 404 | Not Found | The requested resource cannot be found. | | 429 | Too Many Requests | Too many requests were made within a time period. Wait before you call the API again. | | 500 | Internal Server Error | The API had an internal server error and cannot process the request. | | 503 | Service Temporarily Unavailable | The API or one of its internal dependent services is unavailable. Your request cannot be processed. Wait a few minutes and try again. |

Pagination

Some API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for resources that support pagination will include pagination parameters and response metadata.

The following resource uses pagination:

/v1/notifications

The default number of results per page and maximum limit might vary by resource. To use a different number of results per page, use the limit query parameter.

For any request that uses pagination, the response includes pagination link objects that specify how to retrieve other pages of results:

first - URL for the first page of results
previous - URL and token for the previous page (if applicable)
next - URL and token for the next page (if applicable)
last - URL and token for the last page

Each pagination link includes an opaque start token that specifies which page to retrieve. To get the next page of results, use the start token from the next link in your subsequent request. The next property is null when there are no more results. The pagination links retain the same limit parameter that is used for the initial request.

Platform Notifications | IBM Cloud API Docs