API & HTTP — REST, Resilience & Caching

Nine packages that form the HTTP infrastructure layer of a Granit application.

Choosing the right modules

Start with the problem you need to solve:

Problem	Module	When to use
Clients retry a POST and create duplicates	Idempotency	Any mutation endpoint called by mobile apps or unreliable networks
A single user floods your API	Rate Limiting	Public APIs, multi-tenant APIs, any endpoint exposed to untrusted clients
One slow tenant blocks requests for others	Bulkhead	Multi-tenant SaaS where tenants share compute resources
API responses are large (JSON lists, reports)	Response Compression	Any API with responses > 1 KB, especially over mobile networks
You need to push events to external systems	Webhooks	Integration partners expect real-time notifications
You are introducing breaking API changes	API Versioning	Any API with external consumers that cannot upgrade simultaneously
Frontend devs need to explore your API	API Documentation	Always — self-service API exploration reduces support requests
Your API returns inconsistent error shapes	Exception Handling	Always — standardizes all errors to RFC 7807 Problem Details
Browser clients call your API cross-origin	CORS	Any API consumed by SPAs or third-party frontends

Most applications need these four from day one

Exception Handling + CORS + API Documentation + API Versioning — these are foundational. Add Idempotency, Rate Limiting, Bulkhead, and Compression as your traffic and integration patterns demand.

All packages

Package	Purpose
CORS	Default policy, ISO 27001 wildcard rejection
API Versioning	URL segment versioning, RFC 8594 deprecation headers
API Documentation	Scalar OpenAPI UI, OAuth2/PKCE, multi-version docs
Exception Handling	RFC 7807 Problem Details, chain of responsibility mapper
Idempotency	Stripe-style middleware, Redis state machine, AES-256 entries
Rate Limiting	SlidingWindow, FixedWindow, TokenBucket, Concurrency algorithms
Webhooks	HMAC-signed outbound webhooks, retry, subscription management
Bulkhead	Per-tenant concurrency isolation, feature-based quotas, Wolverine middleware
Response Compression	Brotli + gzip with safe HTTPS defaults, SSE exclusion

Package dependencies

graph TD
    CORS[Granit.Http.Cors] --> CO[Granit]
    AV[Granit.Http.ApiVersioning] --> CO
    AD[Granit.Http.ApiDocumentation] --> AV
    AD --> SEC[Granit.Users]
    RC[Granit.ResponseCompression] --> CO
    EH[Granit.Http.ExceptionHandling] --> CO
    ID[Granit.Http.Idempotency] --> CA[Granit.Caching]
    ID --> SEC
    RL[Granit.RateLimiting] --> CO
    RL --> EH
    RL --> FT[Granit.Features]
    RL --> SEC

See also

• Architecture: HTTP Conventions — Status codes, Problem Details, DTO naming
• Security module — JWT Bearer, authorization