There are circumstances in which notifications from the Oracle API Platform CS could be seen as desirable.  For example, if you wish to ensure that the developers are defining good APIs and not accidentally implementing APIs that hit the OWASP Top 10 for APIs. Then you will probably configure things such that developer users can design the APIs, configure the policies, but only request an API to be deployed.

However, presently notifications through mechanisms such as email or via collaboration platforms such as Slack aren’t available.  But implementing a solution isn’t difficult.  For the rest of this blog we’ll explore how this might be implemented, complete with a Slack implementation.

The execution of any such activity effectively needs to follow the basic pattern of …

1. detect the condition requiring a notification, such as a deployment request,
2. gather the information so we can provide a meaningful request, for example, the API name being requested,
3. obtain the individuals to notify and the appropriate contact details,
4. send the notifications.

Getting Contact Details

Commonly such notifications often include email. As the API Platform CS now uses Identity Cloud Service (IDCS) it isn’t difficult to obtain members of an appropriate group, and their email addresses. After all, we typically capture into IDCS user email addresses, so they can be reminded of credentials changes etc.  But what about contact addresses that aren’t linked to email – such as slack ids?  Well, fortunately, IDCS does allow its schema to be extended for these very scenarios (the details on how to do this can be found here). So we could easily ensure user identities have additional information.

There is a downside to this approach – that there are additional locations to now manage identity information. Many social platforms including Slack provide the means to identify groups (or channels in Slack terminology) which users with a vested interest or via Identity Management groupings can be made to be members.  Users also have the ability to mute those groups or channels – for example, when on leave etc. All of which means that the task of managing who shouldn’t get notified is handled for us if we can get the message to that group or channel. Not only that, these platforms often provide the means to signal users in other ways if they receive a message when not engaged such as SMS and emails. As a result, eliminating the need to manage these details which can get messy (the existence of products like PagerDuty show how complex such rules can be to ensure the right individual(s) are notified.

So whilst it is possible to work with email (although authenticating with mail servers can be a laborious process so mail servers don’t accidentally spam people), we’re better off using a collaboration platform to drive the notifications and allow the users to tailor notification mechanisms.

Notifications via Slack

Establishing notification through slack is relatively straight forward (although we admittedly encountered a quirk when trying to POST calls with the bulk of the information in a payload body – more on this shortly).

You do need to have admin privileges for the steps involved, but equally, someone can arrange the details you need with very little effort.  The 1st step is to create a channel within you’re slack group (details here, if you don’t know how to do this). In our example, we called this very simply APIs. Once the channel is established, those who need the notifications should join the channel.

The last step is to create a Slack Bot that can interact with the channel and has an appropriate token. As we want to keep this simple and not use the bot to communicate back to the API platform to perform tasks such as confirm an API can be deployed (which is entirely doable). We simply need a bot-based token – you can easily recognize these as they start with xoxb-.

With these two pieces of information, it is possible to build the notification mechanism. As with all the other API Platform utilities I’ve built out some skeleton Groovy code on which we can extend (these can be seen here). As before for, keys get handled by the command line as a list of parameters and all other configurations come from a properties file.  To send a message to Slack we simply need to use the chat.meMessage REST endpoint described here. Our problems came from the fact that we experienced errors saying we weren’t authenticated or the payload didn’t include the mandatory text value.  However Slack provides an API test utility which showed all the information going into the URI and working. So we have taken this approach to get things to work (I don’t normally recommend this approach as URIs can often get logged by network components performing the routing of your request and it includes your API token).

Ther last details are, that we want to ensure we grab a user’s attention in slack. This can be done by incorporating user names or one of several general-purpose addresses such as @here and @channel. To provide flexibility, we’ll allow the preferred approach to be defined through the properties file.

Locating the Requested Deployments and APIs details

With the means to send a nudge to users through Slack, we still need to locate the deployment requests against APIs.  There isn’t a direct API to do this. So we perform it in a couple of nested steps …

1. Get a list of our APIs using the get APIs endpoint.
2. For each of the APIs access the deployment endpoint – either by constructing the URL using the API Id (as we have) or use the HATEOAS links (rel=deployments) provided. Either way, we end up accessing /deployments endpoint. As walking the DOM with Groovy to the APIId is easier – I’ve built the URL.
3. Get the deployment information, then iterate over each of the deployments looking for the desired deploymentState (in this use case it should have a value of REQUESTING).
4. If a get a deploymentState matching our requirement, then we add to the message to send to slack the API name.
5. Finally, as we’re putting the message into the URI, let’s limit the string length and ensure it is suitably encoded.

With that, we can now when run – detect and perform a Slack notification of the APIs requesting to be deployed.

Of course, we can get a lot fancier if we wish, by getting the URL for each API we notify on so that the API Manager can click on a link to the API directly. If you switch to the chatMessage endpoint you can evolve the message significantly further.

The Implemented Script

The script is in my GitHub repository here, along with an example properties file. The properties needed are annotated and of course, you can see previous examples here such as this one, and the documentation about the switch to IDCS and the use of properties here.