An easy and unified way to send notifications

While I was working on a certain project (the amazing flexget) I needed to create a class of notifier plugins that will enable users to send push notifications to their notification provider of choice. It quickly became apparent that this was not a small undertaking, as it meant diving into each provider’s API and trying to implement it.

Along the way you’d encounter confusing docs, missing docs, irregular response patterns, different response formats, different rules of interaction and so forth. Some providers supply their own SDKs, but that means adding more dependencies into an already dependency rich project, not to mention that not all of those dependencies were well maintained, or even maintained at all. There has to be a better way right?

Well it turned out there wasn’t, or at least I couldn’t find one, so I decided to create notifiers, a generic way to interact with many notification providers.

By creating a unified interface I was able to supply a simple way to interact with any implemented notification provider, regardless of the issues I mentioned earlier.

How it’s done

Notification providers APIs (and any other API for that matter) have two things that they share. They accept arguments, some of which are required, and return a response.

To generically implement the first part, I decided to represent each provider API via a JSON schema, which is very popular and not python specific.
For example, Simplepush API's correlating JSON schema for notification looks like this:

{
    "type": "object",
    "properties": {
        "key": {
            "type": "string",
            "title": "your user key"
        },
        "message": {
            "type": "string",
            "title": "your message"
        },
        "title": {
            "type": "string",
            "title": "message title"
        },
        "event": {
            "type": "string",
            "title": "Event ID"
        }
    },
    "additionalProperties": false,
    "required": [
        "key",
        "message"
    ]
}

Obviously other notification provider schema’s can and do look much more complex than this one, but the point is clear. It is very possible to represent an API schema like so.

The next part is sending the notification and generically handling the response and/or error(s). This is done almost exclusively via HTTP requests, which of course means using the Requests) module.

This a one of the parts that requires the most thorough research, as each provider chooses a different way to implement their API. Some providers want a GET request, most prefer a POST request, some use URL-Encoded content type, one prefer JSON body, some want the authorisation to be carried via the headers, some via URL parameters and etc.

Once the requests is sent, the response is parsed into an internal Response object and returned to the user. And that’s it, the easiest way to send notifications!

Source code: https://github.com/liiight/notifiers

notifiers/tech