Is it reasonable to ask API consumer (client) to provide sync response to notification/callback?

Question

We have an API platform which allows user to create and manage a certain type resource.

Client is expected to provide a callback url where our server will send notification to when the resource is updated.

So far all our notification types don't require any response from client. However, we plan to have a new type of notification which requires certain response from client, for example, someone else wants to update the resource and we need to ask client to accept or reject the update.

I see there are 2 options here:

1. Client get the notification, then send out a new request to our server posting its decision. We'd need to have new endpoints to handle different type of actions.

2. We ask client to provide http response with action in the body for this type of notification. No new API endpoint required on our side.

I'm leaning toward #2 because I don't expect client to take long time to make a decision, so completing everything in 1 round trip is more efficient then having client making another call.

The downside I see is that server won't have a chance to validate response and tell client if there's any error with the format, as client is free to put anything in the response.

Anything else I should consider? It seems #2 is the most popular option when it comes to API design, not sure if #1 is anti pattern here.

Answer 1

It does not seem unreasonable to ask for a client to respond synchronously, but...

• What if the client simply holds the connection open?
• What if the client goes down?
• What if the client has to wait for meat ware to respond?
• What if the client believes it has done x, and the server decides to do y because errors in the response, be that from the network, or the client.

And how does that reflect on the software? Would a client walk away happy, frustrated, content?

Its not just the server who has a burning curiosity about the state of the system. The client too needs ways of determining the system state, be that through asynchronous messages, or a polling system.

In short your protocol may have a very happy synchronous response, but you have to add in the equally happy paths of delayed response, and polling, etc... in so far as keeping each individual in the conversation happy with the knowledge they can access.

Anything less will lead to problems in the not so far future, or software that is never used.

Answer 2

I kinda had the same issue on a personal project, and I chose to have both because I also had the use case where the client wants to launch the process without being notified.

It was not that much work on my end (Small code base + proper isolation of the internal process behind an interface), and it put the hard choice of what interface to use on your customer.

If I really had to choose only one, I'd pick the first option as it relies less on the client being clever, and storing the intermediate step will make your process easier to troubleshoot.