Express courier. Direct.
Also overnight.
x25pronto Switzerland takes goods direct to the destination. Small loads go by car. Larger loads go by van or Van XL. Direct, express and overnight trips run Monday to Sunday when a slot is free. Free times are shown in the booking calendar. This keeps the plan clear.
Best practices for idempotency and event versioning in courier APIs
Practical patterns for idempotency keys, deduplication, event versioning and safe migration paths in courier APIs. Focus: reliable bookings and reconciliation.
Quick answer
In short: use structured idempotency keys, server‑side deduplication with deterministic fingerprints, and an explicit event versioning scheme with clear migration paths. These measures prevent duplicate bookings, ease error handling and protect integrations from Zurich to Geneva.
Why idempotency and versioning matter
Courier APIs handle mission‑critical actions: booking pickups, updating routes and cancelling orders. Network retries, client bugs or duplicated requests can create double bookings and inconsistencies. Idempotency prevents repeated effects. Event versioning keeps schema changes backward compatible and enables safe migrations across internal systems and third‑party integrators.
Idempotency key pattern
Use a structured key: {client_id}:{operation}:{hash(payload)}. Example: customer42:createBooking:3f8a7b. client_id separates tenants, operation clarifies action, and hash(payload) captures the important fields. Set a configurable TTL (e.g., 24–72 hours). Store key, result status and server response. On repeated requests with the same key return the same HTTP status and payload.
Server‑side deduplication and deterministic checks
Don’t rely on keys alone. Validate deterministically: check fields such as pickup address, recipient, package dimensions and time window. Maintain a fingerprint column in the DB (e.g., SHA256 over selected fields). If fingerprint and key match, treat the request as a duplicate. Define tolerances for 'similar' requests, for example small shifts in time windows.
Event versioning: strategy and formats
Version events explicitly: event.type, event.version, event.schema. Use MAJOR.MINOR (1.0, 2.0). MAJOR changes are incompatible; MINOR changes are additive. Include a schema identifier (schema_uri or schema_id). Use JSON Schema or Avro for validation and keep old schemas in a repository so consumers can build backward parsers.
Migration paths and compatibility rules
Set rules: 1) Additive fields are safe. 2) Removing or renaming fields is breaking. 3) Provide feature flags for consumers. Plan a deprecation window: notify integrations via webhook and portal 30–90 days before a MAJOR change. Offer an opt‑in for the new version until consumers migrate.
Error handling and reconciliation
Log idempotency events, fingerprints and decision logic. Provide a reconciliation API so partners can poll status and report divergences. Build an operations UI to merge duplicates or resolve conflicts manually. Keep audit trails for compliance and dispute resolution.
Frequently asked questions
How long should an idempotency key be valid?
Common TTLs are 24–72 hours. Choose a window that fits the business flow. For pickup bookings 48 hours is often enough; for longer processes use a longer TTL.
What if payload fields change between retries?
Compare fingerprints. Small non‑critical changes (notes) can be accepted; changes to crucial fields (destination, weight) should break idempotency and require a new booking.
How to handle incompatible event changes?
Introduce a MAJOR version, notify consumers, keep old events readable and provide adapters or transformation layers in your event broker during migration.
Which fields belong in the idempotency hash?
Business‑relevant fields: pickup/delivery address, recipient ID, package dimensions, desired time window and service type. Exclude volatile metadata like timestamps.