Sending an xml message as the payload to a web api

Question

I have been tasked writing a "fire-and-forget" push web application, that can push high-volume XML messages (of several types) to multiple client endpoints over the internet (HTTPS). I don't need a response, or even to know if they've received the message or not - I don't want it to fail at my end if the message doesn't arrive.

In other words, given a url (e.g. https://192.168.3.45/MessageTypeA/v1, https://192.168.3.45/MessageTypeB/v3, etc.), my application should forward a copy of all XML messages of a given type to that url, and if a client is listening at that url then it can do what it likes with those messages.

I can define how the client urls are defined, security, etc - there's nothing already existing and so I'm not limited by an existing approach.

I am fairly new to web-based apis. I have been looking into REST, SOAP, WebSub...; and trying to find out what is the best approach for this.

REST-based APIs, it seems to me, act on objects at the receiving end - "GET" the list of trains, or "PUT" an update to the driver, or "POST" a new train, or whatever; which isn't relevant for me here - I guess all I would want in this approach is "POST" an new message of type x, y or z? The point is that the xml message when interpreted may well be a POST or a PUT, but I don't want to be pre-processing the messages to decide that - all I'm doing is providing the endpoint with raw data.

In WebSub language, I think I'm the "publisher" and I'm publishing to multiple "Hubs"? But the difference is there's no subscriber in my scenario - I maintain the list of targets per message type, rather than them subscribing.

So I don't really know which protocol/approach is best for this kind of scenario, and so am looking for some advice. Whichever protocol I use needs to allow for encryption on the message and authentication by the receiving client, to ensure it's me sending them messages.

Answer 1

This kind of thing, where you maintain a list of URLs for web endpoints to which you send data, is called a web hook. Github sends web hooks, for example.

Don't overthink it. Keep your protocol simple.

You certainly don't have to tell the consumers of your web hook that they must implement perfect and wonderful REST semantics. Those semantics make the most sense if the purpose of each of your web hooks operations is to transfer state for particular nameable entities. So, for example, if each XML document you're pushing out via a web hook sets or updates, let's say, a particular item of inventory: sales of a chair with a particular product number, then REST might make sense.

Presumably your web hook messages are idempotent: that is, presumably if you send an identical message to a particular consumer more than once it does the same thing as sending it just once. In REST terms, idempotent messages should be PUT messages. But if REST isn't appropriate, you can use POST. When you explain how to develop a service to accept your web hook operations, it's easier to use POST.

If each message is more of a grab-bag of information simply tell your web hook consumers you'll POST each message to them.

The code you use to POST those messages will have to be resilient to timeouts and other failures of your POST operations, obvs.

And, the recipients of your web hook POSTS need some secure way to validate that the messages are really from you, because cybercreeps. Digital signatures are the gold standard here, used in such operations as SAML Assertions. Github does it more simply using hmac hashes based on a shared API key.