Subscribe to Liberty REST API updates

The Liberty REST API discovery feature now exposes a new REST API, /ibm/api/docs/subscription, which allows users to subscribe to any REST API update, such as new APIs being available or old APIs being removed. This is useful when a user wants to be notified immediately of any changes in the endpoints that are provided by a particular Liberty instance.

Enable subscriptions

In addition to the base apiDiscovery-1.0 configuration, it is required to also configure either websocket-1.0 or websocket-1.1 in your server.xml.

<server>
    <featureManager>
        <feature>apiDiscovery-1.0</feature>
        <feature>websocket-1.1</feature>
    </featureManager>

    <httpEndpoint id="defaultHttpEndpoint"
                  host="*"
                  httpPort="8010"
                  httpsPort="8020"/>

    <keyStore id="defaultKeyStore" password="Liberty"/>
  
    <basicRegistry id="basic" realm="ibm/api">
        <user name="bob" password="bobpwd" />
    </basicRegistry>
</server>

The /ibm/api/docs/subscription endpoint allows for POST requests with a JSON payload in the format:

{ "docType" : String }

Where the String can be one of Swagger_20_JSON or Swagger_20_YAML. The returning JSON payload outlines the type of subscription feed and its URL.

Example request and corresponding response

Request:
{"docType":"Swagger_20_JSON"}
Response:
{
  "feedType": "websocket",
  "feedURL": "wss://myserver.com:8020/ibm/api/docs/subscription/websocket/60db0d79-1863-48f5-a0f9-4fe22a27b82d"
}

You can now use a websocket client to connect to the feed URL. Once connected, any further updates to REST APIs in the Liberty server is pushed through the websocket. The update is either in JSON or YAML format, depending on the subscription.