Code-Memo

Advanced API Concepts

Event-driven APIs

1. Systems react to events (order placed, payment cleared) instead of only synchronous request/response.
2. Delivery is usually at-least-once; consumers must dedupe and handle reordering.
3. Expose subscriptions (webhooks, message streams) with clear schemas and versioning.

Webhooks vs APIs

1. APIs are pull/initiated by the client; webhooks push notifications to the subscriber.
2. Webhooks need signatures, retries with backoff, and idempotent handlers.
3. Offer API polling fallback when subscribers cannot receive inbound HTTPS.

Async APIs

1. Return 202 Accepted with a resource clients poll for status (/jobs/{id}).
2. Document final states, timeouts, cancellation, and partial progress if exposed.
3. Align with message brokers or workflow engines for long-running work.

Long polling vs SSE vs WebSockets

1. Long polling: hold a request open until data arrives or timeout; simple but chatty at scale.
2. SSE: one-way server→browser over HTTP; great for dashboards and live updates with standard infra.
3. WebSockets: full-duplex; ideal for chat, games, collaborative UIs; needs connection management and auth at upgrade time.

API composition in microservices

1. BFF or experience APIs aggregate domain calls per client; avoid “chatty” public apps hitting dozens of services.
2. Watch distributed transactions; prefer sagas, outbox, and compensating actions over two-phase commit across HTTP.
3. Keep ownership boundaries clear: one team owns a surface area end-to-end where possible.