Changelog

All notable changes to the yAppointment API are documented here. This project follows Semantic Versioning.

[1.0.0] — 2026-04-19

Initial Release

The yAppointment Integration Platform v1.0.0 is now available with comprehensive REST API, OAuth2 authentication, webhooks, embeddable widget, and TypeScript SDK.

New

• REST API v1

  • Public endpoints for browsing companies, services, employees, available time slots
  • Connected endpoints for creating and managing bookings, customers
  • Authenticated company profile access (GET /api/v1/me)
  • Analytics endpoints for booking summaries

• API Key Authentication

  • Server-to-server integration with public keys (yapp_pk_*) and secret keys (yapp_sk_*)
  • Live and test modes for sandbox development
  • Scope-based permissions (read:profile, write:bookings, read:customers, etc.)
  • Key rotation with 7-day grace period
  • Key revocation with instant enforcement

• OAuth 2.1 Authorization Code Flow with PKCE

  • User-consent based third-party app authorization
  • Authorization endpoint with consent screen
  • Token and refresh token exchange
  • Automatic refresh token rotation
  • Token revocation
  • 60-minute access token TTL, 90-day refresh token TTL

• Webhook System

  • Event delivery for bookings, customers, services, and employees
  • HMAC-SHA256 signature verification
  • Automatic retry with 7 attempts (1m, 5m, 30m, 2h, 6h, 24h, 48h schedule)
  • Dead-letter queue for permanent failures
  • Webhook management UI in Developer Portal

• Event Types

  • booking.created, booking.updated, booking.cancelled, booking.completed, booking.no_show
  • customer.created, customer.updated
  • service.updated, employee.updated

• Rate Limiting

  • Per API key: 1000 requests/minute
  • Per OAuth token: 1000 requests/minute
  • Per IP (unauthenticated): 60 requests/minute
  • Per widget public key: 300 requests/minute per IP
  • Sliding window counter with Redis
  • Rate limit headers and Retry-After guidance

• Embeddable JavaScript Widget

  • Vanilla JavaScript, no dependencies
  • Shadow DOM isolation for styling independence
  • Service, employee, and location selection
  • Available time slot picker
  • Customer information form
  • Support for light/dark themes
  • Multilingual (English, Hungarian)
  • Mobile responsive and accessible (WCAG 2.1 AA)
  • CDN hosted at https://js.yappointment.com/v1/widget.js

• TypeScript SDK (@lohisoftsro/yappointment-sdk)

  • Auto-generated from OpenAPI 3.1 specification
  • 100% type-safe API client
  • Works in Node.js 18+, browsers, Deno, and Bun
  • Built-in webhook signature verification helper
  • Comprehensive TypeScript types and JSDoc

• Developer Portal (developers.yappointment.com)

  • Scalar-based interactive API reference
  • Getting Started guides (overview, authentication, first request, sandbox mode)
  • Detailed guides (OAuth Connect, creating bookings, webhooks, widget embedding)
  • API reference with code examples (curl, Node.js, Python)
  • Webhooks reference with event schemas
  • SDK documentation and code generation guides
  • Error code reference with examples and retry guidance
  • Rate limit documentation and best practices
  • Changelog and API versioning policy
  • Terms of Service for developers
  • Brand guidelines for "Built with yAppointment"
  • Responsible disclosure and security policy

• Developer Portal (Admin UI)

  • API Key management (create, list, revoke, rotate, usage logs)
  • OAuth App registration and management
  • Webhook endpoint CRUD and delivery log viewer
  • API request log viewer with advanced filtering
  • Test mode toggle with sandbox data reset
  • Real-time usage charts and statistics

• Idempotency

  • idempotencyKey parameter for safe retries
  • 24-hour window for idempotent request deduplication
  • Mismatch detection when submitting the same key with different parameters

• Data Models

  • MongoDB collections: api_keys, oauth_apps, oauth_tokens, oauth_authorization_codes, webhook_endpoints, webhook_events, webhook_deliveries, api_request_logs, api_idempotency_keys
  • 30-day retention for logs and events
  • 90-day retention for refresh tokens
  • TTL-based automatic cleanup

• Security

  • Argon2id password hashing for API keys and OAuth secrets
  • AES-256-GCM encryption for webhook signing secrets
  • HMAC-SHA256 signing for webhook payload verification
  • HTTPS-only enforcement
  • CORS configuration for public and connected endpoints
  • PII protection in logs (body content redacted)
  • Company isolation and multi-tenant security
  • Webhook HTTPS-only requirement
  • Refresh token rotation and reuse detection

• Logging and Observability

  • Every request logged with unique request_id
  • Structured JSON logging to stdout
  • MongoDB persistence of API request logs (30-day retention)
  • Authorization header redaction in all logs
  • Webhook delivery logging with attempt details
  • Error tracking with stack traces

Breaking Changes

None — initial release.

Deprecations

None — initial release.

Migration

None required — initial release for new integrations.

Known Limitations

• GraphQL not supported (REST API only)
• gRPC not supported
• Mobile SDKs (iOS/Android) not provided; use web widget via WebView
• Programmatic company provisioning not supported (OAuth Connect flow only)
• SSO between yAppointment admin and external systems not included

Next Steps

See Getting Started to begin integrating with yAppointment API.

Versioning Policy

API Versioning

• URL-based versioning: /api/v1/, /api/v2/, etc.
• Breaking changes trigger major version: /api/v2/
• Minimum 12-month support window between versions
• Deprecation warnings via HTTP header and Developer Portal banner

SDK Versioning

Follows Semantic Versioning:

• Major version aligns with API major version (1.x.x → v1 API)
• Minor version for new features
• Patch version for bug fixes

What Constitutes a Breaking Change

Breaking changes require a new API version:

• Endpoint removal
• Required field removal from response
• Field type change
• Semantic change to field meaning
• New required request field

Non-breaking (safe additions):

• New endpoints
• New optional request fields
• New response fields
• Expanding enum values (when well-documented)