JSON is a convenient format for exchanging data between applications, but large JSON payloads can create performance problems in ASP.NET Core APIs. An endpoint that works perfectly with a few hundred records may become slow when clients start sending tens of thousands of records in a single request.
The problem is not always the size of the HTTP request itself. Processing a large JSON document can consume significant memory, increase CPU usage, trigger frequent garbage collection, and keep server resources occupied for longer periods. If multiple clients send large requests simultaneously, the impact can become even more noticeable.
Increasing the request size limit might solve an immediate error, but it does not make the application more efficient. A better approach is to understand how ASP.NET Core reads and processes JSON, reduce unnecessary memory allocations, and use streaming when the workload allows it.
This article explores practical techniques for handling large JSON payloads while keeping ASP.NET Core APIs responsive and reliable.
Why Large JSON Payloads Affect API Performance
Consider an API that receives customer records from another application. A normal request might contain a few hundred customers, but a bulk synchronization process could send 50,000 or more records in one JSON array.
For a small request, the application can usually read and deserialize the data without noticeable overhead. With a much larger request, several operations happen together:
The server receives and reads a large HTTP request body.
The JSON parser processes the incoming data.
Objects and collections are allocated in memory.
Validation rules execute against the deserialized objects.
The application performs database operations or other business logic.
The garbage collector eventually needs to clean up temporary objects.
Each operation adds work. The problem becomes more serious when the application creates additional copies of the same data.
For example, reading the complete request body into a string and then deserializing that string creates an additional large object in memory. The deserialized object graph requires its own memory as well.
A request containing 30 MB of JSON does not necessarily require only 30 MB of memory while being processed. Depending on the structure, string representations, object allocations, collections, and application logic, the actual memory requirement can be considerably higher.
The impact is also multiplied by concurrency. If several requests are being processed at the same time, memory consumption and CPU usage can increase quickly.
This is why large-payload performance should be evaluated under realistic traffic conditions rather than by testing one request in isolation.
Avoid Reading the Entire Request Body Into a String
One common implementation is to read the complete request body using ReadToEndAsync() and then pass the resulting string to the JSON deserializer.
For example:
app.MapPost("/customers/import", async (HttpContext context) =>
{
using var reader = new StreamReader(context.Request.Body);
var json = await reader.ReadToEndAsync();
var customers = JsonSerializer.Deserialize<List<Customer>>(json);
if (customers is null)
{
return Results.BadRequest();
}
// Process customers
return Results.Ok();
});
This implementation is straightforward, but it is not a good default for large payloads.
The application first reads the complete request into a string. It then creates a collection of customer objects from that string. The original string remains in memory while the application processes the collection, unless it becomes eligible for garbage collection.
For a large request, this can create unnecessary memory pressure.
ASP.NET Core's normal model-binding pipeline already supports JSON request deserialization. For ordinary request sizes, using a typed request model is generally preferable to manually reading the body.
For example:
public class Customer
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
public string Email { get; set; } = string.Empty;
}
The endpoint can receive the model directly:
app.MapPost("/customers", (List<Customer> customers) =>
{
// Process customers
return Results.Ok(new
{
Received = customers.Count
});
});
This removes the unnecessary manual string-reading step. However, it does not mean that the entire collection is processed one item at a time. The endpoint still receives a fully materialized list.
When the application must process a very large JSON array without holding the entire collection in memory, streaming is worth considering.
Use Streaming to Process Large JSON Arrays
Streaming allows an application to read data progressively instead of requiring the complete collection to be materialized before processing begins.
The System.Text.Json library provides JsonSerializer.DeserializeAsyncEnumerable<T>() for asynchronously reading elements from a root-level JSON array.
For example, suppose an external application sends the following request:
[
{
"id": 101,
"name": "Amit"
},
{
"id": 102,
"name": "Neha"
},
{
"id": 103,
"name": "Rahul"
}
]
Instead of deserializing the entire array into a List<Customer>, the API can read and process individual elements as they become available.
using System.Text.Json;
app.MapPost("/customers/import", async (HttpContext context) =>
{
var processedCount = 0;
await foreach (var customer in
JsonSerializer.DeserializeAsyncEnumerable<Customer>(
context.Request.Body,
cancellationToken: context.RequestAborted))
{
if (customer is null)
{
continue;
}
// Validate and process the current customer.
processedCount++;
}
return Results.Ok(new
{
Processed = processedCount
});
});
Here, DeserializeAsyncEnumerable<Customer>() reads elements from the incoming JSON array asynchronously. The application can process each customer without first creating a list containing every customer in the request.
The RequestAborted cancellation token is important. If the client disconnects or cancels the request, the application can stop reading instead of continuing unnecessary work.
There is an important distinction between streaming and simply using IAsyncEnumerable<T> as a property in a model. Deserializing an object containing an IAsyncEnumerable<T> property with DeserializeAsync<T>() does not automatically provide incremental processing of that property. The deserializer needs to finish reading the object before returning it, so the collection may still be buffered.
For a root-level JSON array, DeserializeAsyncEnumerable<T>() is the more direct option.
Streaming is particularly useful for imports, synchronization jobs, and bulk-processing endpoints. However, it does not automatically make every operation safe or faster. Database operations, validation, and business logic still need to be designed carefully.
Process Records in Batches Instead of Making One Database Call Per Record
Streaming reduces the need to hold the complete request collection in memory, but database processing can still become a bottleneck.
Consider an import containing 50,000 customer records. If the application executes a separate database insert for every customer, it may create thousands of database round trips.
That approach can be expensive even when JSON parsing is efficient.
A practical solution is to combine streaming with batch processing. The API reads records progressively, collects a manageable number of records, processes that batch, and then continues reading.
For example:
const int batchSize = 500;
var batch = new List<Customer>(batchSize);
await foreach (var customer in
JsonSerializer.DeserializeAsyncEnumerable<Customer>(
context.Request.Body,
cancellationToken: context.RequestAborted))
{
if (customer is null)
{
continue;
}
batch.Add(customer);
if (batch.Count >= batchSize)
{
await customerService.SaveBatchAsync(
batch,
context.RequestAborted);
batch.Clear();
}
}
if (batch.Count > 0)
{
await customerService.SaveBatchAsync(
batch,
context.RequestAborted);
}
This example keeps the application working with smaller groups of records rather than a complete collection.
The batch size should be selected according to the database, record structure, available memory, and expected concurrency. A batch of 500 might be reasonable for one workload but unsuitable for another.
The database layer should also use an appropriate bulk-insert or batch-update strategy when available. Simply putting records into a list and calling SaveChangesAsync() repeatedly does not guarantee that the database operation is efficient.
There is another important consideration: partial processing.
If the API successfully saves five batches and encounters invalid data in the sixth, the first five batches may already have been committed. If the business requirement is that the entire import must succeed or fail as one operation, a simple streaming implementation is not enough.
In that situation, consider validating and staging records before applying them, using an appropriate transaction strategy, or processing the import through a durable background workflow.
Configure Request Size Limits Carefully
ASP.NET Core servers enforce request body size limits to protect applications from excessively large requests.
Kestrel's default maximum request body size is 30,000,000 bytes, approximately 28.6 MB. An API receiving larger requests may return an error before the application processes the payload.
If a particular endpoint genuinely needs to accept larger requests, configure the limit deliberately.
For example, the following configuration increases the Kestrel request body limit to 100 MB:
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(options =>
{
options.Limits.MaxRequestBodySize = 100 * 1024 * 1024;
});
var app = builder.Build();
app.Run();
However, increasing this limit globally means that all applicable endpoints can accept larger request bodies. That may not be necessary.
A more targeted approach for an MVC controller action is to use RequestSizeLimit:
[ApiController]
[Route("api/customers")]
public class CustomersController : ControllerBase
{
[HttpPost("import")]
[RequestSizeLimit(100 * 1024 * 1024)]
public IActionResult Import()
{
// Handle the import request.
return Accepted();
}
}
The request size limit should reflect an actual business requirement. Avoid disabling the limit without a clear reason.
Also remember that Kestrel might not be the only component enforcing the limit. IIS, reverse proxies, API gateways, and other hosting infrastructure can have their own request-size restrictions.
For example, an IIS request filtering limit can reject a request before it reaches the ASP.NET Core application. Increasing the Kestrel limit alone will not override that restriction.
Most importantly, a larger request size limit does not improve JSON parsing performance. It only allows a larger request to reach the application. The API still needs suitable streaming, validation, concurrency, and resource-management strategies.
Keep JSON Deserialization Efficient
Streaming is not always necessary. Some APIs receive moderately sized JSON documents that can be handled comfortably using normal model binding.
In these cases, it is worth examining the deserialization process itself.
The built-in System.Text.Json serializer is generally a good starting point for ASP.NET Core applications. Before introducing custom converters or lower-level parsing, measure the existing implementation and identify the actual bottleneck.
Avoid unnecessary transformations of the request data. For example, converting a JSON string into another intermediate representation before creating the final DTO introduces additional work.
Keep DTOs focused on the data the endpoint actually needs. A request model containing deeply nested objects, large collections, and unnecessary properties can increase deserialization and validation costs.
Consider this example:
public class CustomerImportRequest
{
public int CustomerId { get; set; }
public string Name { get; set; } = string.Empty;
public string Email { get; set; } = string.Empty;
public string? Notes { get; set; }
}
A focused DTO is easier to validate and process than a large object graph containing unrelated application data.
If custom serialization behavior is required, use JsonSerializerOptions deliberately. For example, property naming policies and custom converters should be introduced because the API needs them, not simply because they are available.
For applications that repeatedly deserialize the same DTO types, source-generated JSON metadata can also be considered. It can reduce reflection-related work and improve serialization efficiency in suitable scenarios.
However, it is important to understand what source generation does and does not solve. It does not eliminate the memory required for a fully materialized object collection. If the primary problem is holding too much data in memory, streaming or a different API contract is still necessary.
Stream Large JSON Responses When Appropriate
Large payloads can affect outgoing responses as well as incoming requests.
For example, an API might return hundreds of thousands of transaction records in one response. Building the complete collection before returning it can increase memory usage and delay the first response data.
ASP.NET Core supports asynchronous serialization of IAsyncEnumerable<T> values through System.Text.Json.
A minimal API endpoint can return an asynchronous sequence:
app.MapGet("/transactions", async (
ITransactionService transactionService) =>
{
return Results.Ok(
transactionService.GetTransactionsAsync());
});
The service can expose an asynchronous sequence:
public interface ITransactionService
{
IAsyncEnumerable<Transaction> GetTransactionsAsync();
}
The implementation can retrieve records progressively from an appropriate data source.
public async IAsyncEnumerable<Transaction>
GetTransactionsAsync()
{
await foreach (var transaction in
repository.GetTransactionsAsync())
{
yield return transaction;
}
}
This approach can avoid building one large list before serialization starts. It is useful when the underlying data source also supports incremental access.
However, returning IAsyncEnumerable<T> does not guarantee that the complete request-to-response pipeline is free from buffering. Database providers, middleware, reverse proxies, response compression, and clients can all influence how data is delivered.
The API should also consider what happens if the client disconnects while the response is being generated. Long-running database queries and other resources should be released promptly when cancellation occurs.
For very large result sets, pagination is often a better API design than returning one enormous JSON array.
Prefer Pagination for Large Data Retrieval
Streaming can be useful, but it is not always the best solution for APIs that return large collections.
If a client needs to browse customer records, transaction history, or product information, returning everything in one response creates unnecessary work for both the server and the client.
Pagination limits the amount of data returned in each request.
For example:
GET /api/transactions?pageNumber=1&pageSize=100
The API returns a limited number of records and allows the client to request the next page when needed.
A response might look like this:
{
"pageNumber": 1,
"pageSize": 100,
"totalCount": 25000,
"items": [
{
"id": 1001,
"amount": 2500
},
{
"id": 1002,
"amount": 1800
}
]
}
For large or frequently changing datasets, cursor-based or keyset pagination can be more suitable than offset-based pagination. It can avoid some of the database work associated with skipping increasingly large numbers of records.
The API should also enforce a reasonable maximum page size. Otherwise, a client could request an extremely large page and recreate the same performance problem.
For bulk exports, consider generating the export asynchronously and allowing the client to retrieve the completed file. For imports, consider accepting a file or creating a background processing job instead of keeping an HTTP request open for a long-running operation.
The right approach depends on whether the client needs interactive access, bulk transfer, or background processing.
Avoid Common Mistakes When Handling Large JSON Payloads
Several implementation choices can make large-payload problems worse, even when the API uses asynchronous methods.
Common mistake | Why it causes problems | Better approach |
|---|
Reading the complete body into a string | Creates an additional large in-memory representation | Use model binding or stream-based deserialization |
Increasing the request limit without controls | Allows larger requests without addressing resource consumption | Apply endpoint-specific limits |
Processing every record with a separate database call | Increases database round trips | Use suitable batch operations |
Creating one enormous response collection | Increases memory usage before serialization | Use pagination or streaming |
Logging complete request bodies | Can increase memory, storage, and processing overhead | Log metadata and selected identifiers |
Allowing unlimited concurrent imports | Can exhaust application and database resources | Apply concurrency limits and backpressure |
Ignoring cancellation | Allows unnecessary work to continue after a client disconnects | Pass cancellation tokens through the processing pipeline |
One mistake deserves particular attention: logging large request bodies.
Developers sometimes enable request and response body logging to troubleshoot an API. This can be useful for small requests, but logging complete payloads can create another expensive processing path. It may also expose personal information, authentication-related data, or other sensitive values.
For large imports, log useful metadata instead, such as the request identifier, payload size, number of processed records, processing duration, and failure details.
Test Large Payload Performance Under Realistic Conditions
An API that processes a large request successfully is not necessarily ready for production. It should also be tested under the conditions in which it will operate.
Start by testing different payload sizes. For example, compare requests containing 1,000, 10,000, and 50,000 records. These are test scenarios, not universal thresholds; the appropriate sizes depend on the application's requirements.
Measure more than response time. Useful metrics include:
Request duration and throughput.
CPU utilization during deserialization and processing.
Managed memory allocation.
Garbage collection frequency and duration.
Number of concurrent requests.
Database query duration and connection usage.
Failed requests and timeouts.
Run concurrent tests as well. A single import might complete successfully, but several simultaneous imports could cause memory pressure or exhaust the database connection pool.
Use realistic DTO structures and validation rules. Testing with a simple object containing two properties may not reveal the cost of deserializing the deeply nested models used by the actual application.
It is also important to test failure scenarios. Send malformed JSON, requests exceeding the configured size limit, incomplete arrays, and requests that are cancelled while processing.
These tests help verify that the application releases resources correctly and does not leave partially processed data in an inconsistent state.
Best Practices for Production ASP.NET Core APIs
Handling large JSON payloads is not about finding one serializer setting that makes every request faster. It requires a combination of API design, resource management, and appropriate processing techniques.
The following practices provide a useful starting point:
Use typed model binding for normal-sized JSON requests instead of manually reading request bodies into strings.
Use DeserializeAsyncEnumerable<T>() when processing a large root-level JSON array incrementally.
Combine streaming with controlled batch processing when records must be written to a database.
Set request body limits according to the actual requirements of each endpoint.
Check IIS, reverse proxy, and API gateway limits in addition to Kestrel settings.
Keep DTOs focused and avoid unnecessary nested object graphs.
Use pagination for normal data retrieval and consider background jobs for long-running bulk operations.
Pass cancellation tokens through deserialization, database operations, and other asynchronous work.
Avoid logging complete payloads and limit concurrent resource-intensive imports.
Monitor memory, CPU, garbage collection, database performance, and request duration under realistic concurrency.
These practices should be applied according to the workload. An endpoint receiving a few hundred records does not need the same architecture as an endpoint processing millions of records.
Summary
Large JSON payloads can slow down ASP.NET Core APIs because reading, deserializing, validating, and processing large collections consumes memory and CPU resources. The impact becomes more significant when multiple requests are processed concurrently.
Avoiding unnecessary string conversions is a good first step. For large root-level JSON arrays, JsonSerializer.DeserializeAsyncEnumerable<T>() can support incremental processing without materializing the entire collection. Combining streaming with controlled database batches can further reduce memory pressure and improve resource management.
Request size limits should also be configured carefully. Increasing a limit may allow a larger request to reach the application, but it does not make the application more efficient. For many use cases, pagination, bulk-processing jobs, or file-based imports provide a better design than sending enormous JSON documents through a single API request.
The goal is to build APIs that handle the required data volume without consuming unnecessary resources or affecting other requests. Choosing the right processing strategy, testing under realistic concurrency, and monitoring production behavior will help keep ASP.NET Core applications responsive as their workloads grow.
Join the conversation! Your thoughts help the community grow.