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.

  • If you go with #2, is there any problem with the operation serving two purposes?
    – CJL
    Commented Aug 4, 2020 at 4:40
  • 1
    What would happen in #2 if the decision does take a long time (e.g. the client needs to ask a human operator who happens to be away from the computer) and the connection times out? Commented Aug 4, 2020 at 7:25
  • @BartvanIngenSchenau it's not suppose to take a long time and human operator should not be involved. i'm thinking timeout handling would be the same between #1 and #2 where we need to fall back to some default action, say reject. Commented Aug 4, 2020 at 18:45
  • @CJL do you mean the callback serve as both a notification and demand a response as two purposes? Commented Aug 4, 2020 at 18:46

2 Answers 2


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.

  • * a client can hold connection open no matter if we require a response or just 202 * client goes down is similar for 202 * the use case demand immediate response anyway, shouldn't have human involved * this one is a good point, server won't have a chance to validate response and notify client on any error I see your point, i'm thinking since the current case is simple enough, no need polling, not much validation, and don't expect delay response etc. thinking to just go with sync path and as situation comes up we go to async? can avoid premature optimization this way i think Commented Aug 4, 2020 at 18:37
  • 1
    Just laying out the situation, its up to you to decide what goes.
    – Kain0_0
    Commented Aug 4, 2020 at 23:37

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.