Adaptive Bitrate Streaming for Mobile API Responses: Dynamic Payload Shaping Under Network Pressure

---

title: "Adaptive API Payloads for Mobile Under Network Pressure"

published: true

description: "Build a Ktor middleware pipeline that detects client bandwidth and progressively degrades JSON payload fidelity without changing your API contract."

tags: kotlin, mobile, api, architecture

canonical_url: https://mvpfactory.co/blog/adaptive-api-payloads-mobile-network-pressure

---

What We Will Build

By the end of this workshop you will have a three-layer Ktor middleware pipeline that reads client-reported bandwidth, maps your data model fields to degradation tiers via a custom annotation, and shapes the JSON response at runtime — dropping non-critical fields, collapsing nested objects to ID references, and stripping embedded assets. The API contract stays identical. Existing clients require zero changes.

Internal benchmarking on a Ktor-based streaming service showed payload size accounting for 38–52% of perceived response time on sub-2 Mbps cellular connections. HTTP/2 and gzip alone do not close that gap. Progressive fidelity degradation does.

Prerequisites

• Kotlin + Ktor 2.x project


• Familiarity with Ktor plugins and onCallRespond
  


• Kotlin reflection on the classpath (kotlin-reflect)

The Architecture

Client Request

     │

     ▼

[Bandwidth Estimation Middleware]  ← reads timing headers

     │

     ▼

[Payload Priority Resolver]        ← maps model fields to tiers

     │

     ▼

[Response Shaper]                  ← serializes only eligible fields

     │

     ▼

Client Response

Step 1 — Client-Side Bandwidth Estimation

Clients self-report estimated bandwidth through a custom request header, computed from prior response timing:

val estimatedKbps = (lastResponseBytes * 8) / lastResponseDurationMs

request.header("X-Client-Bandwidth-Kbps", estimatedKbps.toString())

This is lightweight and privacy-safe. No IP geolocation, no server-side probing. The server reads what the client already knows from its own timing data.

Step 2 — Annotate Your Response Models

Here is the pattern I use in every project. Define degradation tiers directly on data class properties:

@Target(AnnotationTarget.PROPERTY)

annotation class PayloadPriority(val tier: Int) // 1=critical, 3=droppable



data class TrackResponse(

    @PayloadPriority(1) val id: String,

    @PayloadPriority(1) val title: String,

    @PayloadPriority(2) val artist: ArtistSummary,

    @PayloadPriority(3) val artworkUrl: String?,

    @PayloadPriority(3) val lyrics: String?

)

Tier thresholds map to bandwidth buckets:

In Reduced mode, ArtistSummary collapses to artistId: String — honoring the contract shape while dropping payload weight.

Step 3 — Wire the Ktor Middleware

First, the interface that marks response models as shapeable:

interface HasPayloadPriority {

    fun shapeTo(maxTier: Int): Map<String, Any?>

}

Then the plugin itself:

fun Application.installAdaptivePayload() {

    install(createRouteScopedPlugin("AdaptivePayload") {

        onCallRespond { call, body ->

            val bwKbps = call.request.header("X-Client-Bandwidth-Kbps")

                ?.toIntOrNull() ?: Int.MAX_VALUE



            val tier = when {

                bwKbps > 5000 -> 3

                bwKbps > 1000 -> 2

                bwKbps > 300  -> 1

                else          -> 1

            }



            if (body is HasPayloadPriority) {

                transformBody { body.shapeTo(tier) }

            }

        }

    })

}

The shapeTo implementation uses reflection over @PayloadPriority to build a filtered map:

override fun shapeTo(maxTier: Int): Map<String, Any?> {

    return this::class.memberProperties

        .filter { prop ->

            val priority = prop.findAnnotation<PayloadPriority>()

            priority != null && priority.tier <= maxTier

        }

        .associate { prop ->

            val value = prop.getter.call(this)

            prop.name to when {

                value is HasPayloadPriority -> value.shapeTo(maxTier)

                maxTier < 2 && value is IdResolvable -> value.id

                else -> value

            }

        }

}

The docs do not mention this, but cache the reflected property list per class. Run a warm-up call at startup and store results in a ConcurrentHashMap<KClass<*>, List<KProperty1<*, *>>> — per-request reflection overhead will otherwise surface under load.

What You Get in Production

Here is the minimal setup running on a real Ktor streaming service:

No route changes. No API versioning.

Gotchas

Caching breaks silently. CDN and client-side caches must vary on bandwidth tier. Add Vary: X-Client-Bandwidth-Kbps to your response headers or use tier-bucketed cache keys. A minimal-mode response cached and served to a full-mode client is a silent, hard-to-reproduce bug.

ID-only references require client resilience. When you collapse objects to IDs in Reduced mode, your UI layer must tolerate partial hydration. If it cannot, this degradation mode creates regressions, not just missing fields. Design for it upfront.

Annotation drift is the slow killer. As models evolve, tier assignments go stale. Add a lint rule that fails the build on any public response field missing @PayloadPriority, and make tier review mandatory in code review for new response models. Retrofitting this onto an unannotated codebase is painful — do not skip the annotation step during initial model design.

Conclusion

Treat payload fidelity as a delivery concern, not a schema concern. Your API contract defines shape, not weight. Start by instrumenting X-Client-Bandwidth-Kbps in your client now — even before building the shaping pipeline. That real-world network distribution data is what you need before you can set thresholds that actually match your users' conditions. Most teams skip this and argue from gut feel. Do not be those teams.

Further reading: Ktor plugin documentation · Kotlin reflection