API Best Practices

Sync vs Async

When integrating with TempoDB, one decision you'll face is whether the communication should be synchronous or asynchronous. The TempoDB libraries are designed to be synchronous, meaning that when you make a request, your code stops and waits for a response (just like reading a file or writing to a local database). This allows you to quickly get up and running, and gives you easy visibility into the responses you're getting from us.

When you're reaching out across the Internet to some 3rd party service, there will always be a risk that requests are slow, or don't make it at all. This may be because of latencies/failures in general internet routing (Internet Health Report), or it may be because the 3rd party (TempoDB in this case) is having some issue. Of course, we make every effort to maintain complete uptime, but it is generally a good idea to be defensive on your side. As such, it is strongly recommended that you use our libraries asynchronously, allowing your service to gracefully handle any potential interruption.

The details of how you implement asynchronous communication is specific to your language and infrastructure, but a common practice is to write all your TempoDB data to a queue (eg, Kestrel or Celery), and have one or more workers pulling off the queue and writing to us (using our client libraries). A strategy along these lines allows you to handle errors, retries, and general latency out-of-band.