Skip to content
Granit
Blog

API & HTTP — REST, Resilience & Caching

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

Choosing the right modules

Section titled “Choosing the right modules”

Start with the problem you need to solve:

ProblemModuleWhen to use
Clients retry a POST and create duplicatesIdempotencyAny mutation endpoint called by mobile apps or unreliable networks
A single user floods your APIRate LimitingPublic APIs, multi-tenant APIs, any endpoint exposed to untrusted clients
One slow tenant blocks requests for othersBulkheadMulti-tenant SaaS where tenants share compute resources
API responses are large (JSON lists, reports)HTTP HostingAny API with responses > 1 KB, especially over mobile networks
You need to push events to external systemsWebhooksIntegration partners expect real-time notifications
You are introducing breaking API changesAPI DocumentationAny API with external consumers that cannot upgrade simultaneously
Frontend devs need to explore your APIAPI DocumentationAlways — self-service API exploration reduces support requests
Your API returns inconsistent error shapesException HandlingAlways — standardizes all errors to RFC 7807 Problem Details
Browser clients call your API cross-originHTTP HostingAny API consumed by SPAs or third-party frontends

All packages

Section titled “All packages”
PackagePurpose
HTTP HostingAuto-registered CORS with ISO 27001 wildcard rejection, Brotli + gzip compression
API DocumentationOpenAPI 3.1, URL-segment versioning, RFC 8594 deprecation, Scalar UI (.Scalar companion), OAuth2/PKCE
Exception HandlingRFC 7807 Problem Details, chain of responsibility mapper
IdempotencyStripe-style middleware, IIdempotencyStore contract, Redis provider with AES-256-GCM entries
Rate LimitingSlidingWindow, FixedWindow, TokenBucket, Concurrency algorithms
WebhooksHMAC-signed outbound webhooks, retry, subscription management
BulkheadPer-tenant concurrency isolation, feature-based quotas, Wolverine middleware
URL SafetySSRF-safe outbound URL validation

Package dependencies

Section titled “Package dependencies”
graph TD
    HOST[Granit.Http.Hosting] --> CO[Granit]
    AD[Granit.Http.ApiDocumentation] --> SEC[Granit.Users]
    ADS[Granit.Http.ApiDocumentation.Scalar] --> AD
    EH[Granit.Http.ExceptionHandling] --> CO
    IDA[Granit.Http.Idempotency.Abstractions] --> CO
    ID[Granit.Http.Idempotency] --> IDA
    ID --> SEC
    IDR[Granit.Http.Idempotency.StackExchangeRedis] --> ID
    RL[Granit.RateLimiting] --> CO
    RL --> FT[Granit.Features]
    HRL[Granit.Http.RateLimiting] --> RL
    HRL --> EH
    BH[Granit.Bulkhead] --> FT
    HBH[Granit.Http.Bulkhead] --> BH
    HBH --> EH

The rate-limiting and bulkhead cores are framework-pure — Granit.Http.RateLimiting and Granit.Http.Bulkhead are the ASP.NET Core bindings (endpoint filter + RFC 7807 mapping), and Granit.RateLimiting.Wolverine / Granit.Bulkhead.Wolverine the message bindings. See Rate Limiting, Bulkhead and ADR-062.

See also

Section titled “See also”