ruk·si
/notes

API
Requst Lifecycles

Updated at 2021-03-10 13:23

Most API endpoints are synchronous, but you frequently need bits of asynchronousity.

  • Synchronous API the caller gets the answer right away.
  • Asynchronous API the caller doesn't get the answer right away.

Decide your main approach to create asynchronous endpoints. It usually doesn't take long that you need some long-running operations to be performed on your API. You might want to think how to handle these.

  • Polling API you send a request and somehow poll is the operation done.
  • Callback API the caller provides a callback URL that will be notified after the operation.
  • Event-based API means that you have event-based publish-subscribe approach.

Polling APIs

Consider using HTTP status codes to create polling APIs. Client will handle the use the APIs by polling as they see fit.

POST example.com/api/batch-job-inquiry (with unique identifier)
    => 202 Accepted
    => 202 Accepted
    => 202 Accepted
    => 201 Created (with the ID 1234 for the next GET lookup or Location field)
GET example.com/api/batch-job/1234
    => 200 OK (with information about the batch job)

Many name these calls-for-action "requests" but I like to use another noun.

Consider using ATOM to publish events. If you don't want to introduce new technology into your stack, ATOM might be an option. ATOM is a REST compliant feed system that you can use. It does require subscribers to poll for event, and managing shared state is horrible e.g. "has this event been processed already?". Not usable for large scale services.

Event-based APIs

Event-based endpoints are frequently worker-based. You have a queue of jobs and workers pull jobs from there. Good for peaky workloads as you can easily add more workers when needed.

Keep your middleware technology dumb like RabbitMQ or other simple message queue. If you place too much logic to the middleware, it will be harder to move on top of other technologies and environments.

Implement dead letter queue. Dead letter queue is a queue or other location where you place events that failed to be processed even after multiple trials. It is essential that you have max trials ber job event or one bad payload can crash each and every worker. Dead letter queue is for debugging the payload later.