APIs usually respond to requests quickly. But what happens when a request takes a long time to process? That’s where the LRO (Long-Running Operations) design pattern comes in. It’s a smart way to handle tasks that take a while to complete, but it brings some challenges, especially with how clients handle waiting and errors.
Sometimes, the server needs more time to process a request. Maybe it’s a complex operation or something involving large data. In these cases, simply telling the client, "Wait, we’ll get back to you" isn’t enough. Many clients won’t read the documentation properly, so they might stop waiting after a few minutes and try again, which only adds to the server load. Or, they might not know how long to wait or whether the server is even doing anything useful.
Then there’s the issue of cancellations. What if the client wants to stop the process or pause it? And, if the connection drops, does the process restart from scratch?
The LRO pattern works like this: first, the client creates an LRO object. This object has an operation ID (ID), which the client can use to track the progress of the task. The client can also pause, resume, or cancel the operation at any point.
Typically, the LRO object will have a few key fields: an ID, a result field (which contains the operation's final output), and a done field to indicate whether the operation is finished or still in progress. Sometimes, checking if the result field is empty can tell you if the process is done. But for operations where there’s nothing to return (like deleting a file), the done field is crucial.
One tricky thing about LROs is how to handle errors. Normally, an API would return a status code like 500 for an error. But with LROs, it’s not always clear if that error is related to tracking the operation or the operation itself. So, instead of just using status codes, LROs return errors as JSON objects within the response body. This helps keep things clear.
Also, it’s better to use numerical error codes instead of readable text codes. Why? Text codes are harder to change later if needed (like fixing a typo), while numerical codes are easier for machines to process and more flexible. The explanation of the error can go in a separate details field for clarity.
The LRO pattern is essential for APIs dealing with long-running tasks. It helps clients track progress, pause or cancel tasks, and handle errors more effectively. While it has its challenges, like managing client expectations and dealing with errors, it’s a powerful tool when designed and implemented properly.