Group Scheduling API Design: Idempotency, Retries, and Cross-Company Fallbacks

A production group scheduling API contract

Expose a meeting resource and a small command set. Do not expose one magical ‘schedule’ endpoint that blocks until the world cooperates. The client should be able to create intent, inspect progress, approve a proposal, request a revision, and receive verified state changes.

1. 1

   Create one durable meeting request

   Accept POST /meeting-requests with a client idempotency key. The body should name the organizer, required and optional participants, duration, date window, meeting time zone, working-hour or preference rules, booking deadline, approval mode, and permitted outreach channels. Return 202 Accepted with a stable resource URL when coordination continues asynchronously.
   • The same key and same payload return the same meeting request.
   • The same key with a different payload returns a conflict, not a second request.
   • The response exposes current state, revision, created time, and next expected action.
2. 2

   Separate commands from observed events

   Commands express intent: approve this slot, change the window, add an optional participant, cancel the request. Events record facts: availability received, provider access expired, candidate generated, booking committed, invitation verified. Give every event a unique ID, meeting request ID, revision, sequence number, and occurred-at timestamp. Consumers should deduplicate by event ID and reconcile gaps by reading the meeting resource.
   • Never ask a webhook consumer to infer state from prose.
   • Keep event delivery at-least-once and document ordering boundaries.
   • Expose a full current-state read so a lost webhook is recoverable.
3. 3

   Normalize Google and Microsoft availability

   Put provider calls behind adapters. Google Calendar’s free/busy API and Microsoft Graph’s getSchedule differ in request shape, permissions, limits, errors, and time-zone handling. Convert both into canonical busy intervals with participant ID, source provider, source account, retrieval time, and confidence. Do not pass raw provider payloads into an agent model as your system of record.
   • Use RFC 3339 timestamps at API boundaries and IANA zones for policy.
   • Distinguish an empty busy list from an incomplete provider response.
   • Store permission denial, throttling, and expired credentials as separate reason codes.
4. 4

   Make no-calendar fallback a first-class adapter

   An external participant may never connect a calendar. Model conversational availability as another provider with consent, channel, message ID, requested window, normalized response, freshness, and opt-out state. The API should expose waiting_on_participant rather than hide a message chase behind a generic processing status.
   • Limit reminders and make the policy visible to the organizer.
   • Ask narrow follow-ups for ambiguous dates, zones, or ranges.
   • Do not contact anyone unless the organizer has authority and the channel is allowed.
5. 5

   Version proposals and availability evidence

   A slot proposal is derived data. Include a proposal ID, meeting revision, required-participant overlap, optional-participant score, preference score, and the availability snapshot version behind it. If any required calendar or response changes, mark the proposal stale. Approval of a stale proposal should trigger a re-check, never an unconditional write.
   • Explain which constraint rejected every near-miss slot.
   • Keep required attendance as a hard rule unless the organizer changes the brief.
   • Expire proposals at a documented freshness boundary.
6. 6

   Create an idempotent booking transaction

   The commit path needs its own key, separate from request creation. Derive it from meeting request ID, revision, and approved proposal. Re-read fresh free/busy, acquire a short commit lock, write the organizer event, persist the provider event ID, send attendee updates, and verify the resulting record. If the provider times out, query by stored correlation data before retrying the insert.
   • One approved proposal creates at most one canonical meeting event.
   • A retry returns the prior booking result when the commit already succeeded.
   • A partial failure moves to reconciliation with an explicit operator action.
7. 7

   Close the loop with reconciliation and observability

   Emit traces, metrics, and structured logs around meeting state rather than individual HTTP calls alone. Track time in state, required participants still missing, provider error class, retries, stale proposals, duplicate commit attempts, and invitation verification. Reconciliation workers should compare stored booking state with the provider record after uncertain writes and webhook gaps.
   • Every failure response includes a stable code, retry class, and safe next action.
   • Every meeting can be reconstructed from its command and event history.
   • Sensitive calendar details stay out of logs and model prompts.

Choose the API boundary, not just the API vendor

Provider APIs, booking APIs, and execution APIs solve different layers. The correct choice follows the outcome your agent promises.