Designing a Biometric Attendance API

Design principles

When designing PunchConnect's API, we studied the APIs we admire most: Stripe for consistency, Twilio for webhooks, and GitHub for developer experience. Three principles emerged:

1. Be predictable — consistent naming, response formats, and error codes across every endpoint

2. Be real-time — webhooks for events, not polling. Developers should react to events, not check for them.

3. Be resilient — every operation should be safe to retry. Idempotency keys, deduplication, and at-least-once delivery.

Webhook delivery guarantees

PunchConnect guarantees at-least-once delivery for all webhook events. Here's how it works:

When a punch event occurs, it's written to a durable queue. A delivery worker picks it up and sends the HTTP POST to your callback URL. If your server responds with 2xx, the event is marked as delivered.

If your server is down or responds with 5xx, the event is retried with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 12 hours, 72 hours. After all retries are exhausted, the event is marked as failed and you're notified via email.

Rate limiting strategy

We use a sliding window rate limiter with generous defaults: 1,000 API calls per device per day for REST endpoints, and unlimited for inbound webhooks (device → PunchConnect).

Rate limits are communicated via standard headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. When you hit the limit, you get a 429 response with a Retry-After header.

Idempotency

All mutating endpoints (POST, PUT, DELETE) accept an Idempotency-Key header. If you send the same request with the same key within 24 hours, you get the cached response instead of creating a duplicate.

This is critical for device commands. If you send a "sync employees" command and your network drops before you receive the response, you can safely retry without accidentally triggering a double sync.

Lessons learned

The biggest lesson: real-world biometric data is messy. Devices send duplicate punches, out-of-order timestamps, and occasionally garbage data. Our API normalizes and deduplicates before your webhook receives it, so you get clean, reliable data.