Enterprise API Design

Introduction

Enterprise APIs are contracts that outlast their authors. Treat them like products: versioned, documented, monitored, deprecated gracefully.

Understanding the topic

The enterprise checklist:

• 📝 OpenAPI 3.1 spec generated from code (springdoc-openapi).
• 🔢 Path versioning (/v1) + deprecation headers + sunset dates.
• 🛑 Errors as RFC 7807 Problem JSON.
• 🔁 Idempotency keys on all writes.
• 📊 Pagination, filtering, sorting standardised across endpoints.
• 🔍 Field selection / sparse fieldsets for big resources.
• 🪝 Webhooks with HMAC signatures + retries for outbound events.
• 🧾 SLA + rate-limit headers (X-RateLimit-*).