Calendar
Research
Calendar engineering guide

Calendar API fundamentals for SaaS products

A calendar integration is a long-running replica and command system built around authorized accounts, calendars, events, availability, recurring instances, and provider change state.

Research surface only. This guide documents architecture and evaluation criteria; it does not describe a released DewEngine connector.
01
Domain model

Keep calendar and event ownership explicit

Represent the connected account, target calendar, provider event ID, organizer, attendees, start and end, IANA time zone, all-day status, recurrence, conference data, and provider extension fields.

02
Access

Choose permissions from visible product actions

Read-only availability, event reads, event writes, and tenant-wide service access carry different consent. Prefer delegated user access for user-owned scheduling and reserve administrative modes for explicit enterprise requirements.

  • Calendar discovery
  • Free/busy or schedule read
  • Event create/update/delete
  • Shared calendar access
03
Synchronization

Use initial state plus provider deltas

Build a bounded baseline, persist Google sync tokens or Graph delta links per collection, and use provider notifications to trigger incremental reads. Expired state must enter a controlled full-resync path.

04
Hard cases

Test time and recurrence as product behavior

All-day events, daylight-saving transitions, recurring exceptions, moved instances, organizer changes, attendee responses, and concurrent edits are core cases. Preserve provider versions such as ETags or change keys for conflict-aware writes.

  • DST boundary
  • All-day exclusive end
  • Recurring master and exception
  • Optimistic concurrency conflict
Questions

Before you build.

Should event times be stored only as UTC?+

Store an absolute instant where applicable and retain the event's named time zone. Recurrence and daylight-saving behavior cannot be reconstructed safely from a UTC offset alone.

Do calendar webhooks contain the full changed event?+

Not always. Google Calendar watch notifications contain no changed-resource body, and other provider payload modes vary. Design the webhook as a trigger for authoritative retrieval.

Can I use DewEngine's calendar connectors today?+

Not as released connectors. Google Calendar has one feature-flagged development method, calendar.event.create, plus list/get for DewEngine-confirmed creates and the resulting canonical creation event. Provider calendar reads and sync, update/delete, availability, recurrence, watches, and Microsoft Graph Calendar remain planned. The implemented slice has only local fake-provider evidence, not real-account or production conformance.

Build with us

Does this match the workflow your users need?

DewEngine is in development. Real use cases decide what ships first.

Share your use case