Lesson 4
Returning Other Data Types in Minimal APIs
Introduction

Welcome back! You've come a long way in mastering ASP.NET Core Minimal APIs. Throughout this course, you've learned to set up endpoints, handle HTTP requests, and build robust JSON APIs. As we approach the final lesson, we'll explore how to return different types of data from your API endpoints. Specifically, we’ll cover how to return files, binary data, and streams asynchronously. These skills will make your APIs more versatile and powerful, allowing you to handle a wide range of use cases.

Returning Files

In some situations, you'll need to return files from your API. ASP.NET Core provides the Results.File method to facilitate this. It enables you to send a file to the client with minimal effort. Here’s how to set up an endpoint that allows users to download a file from the server:

C#
1var builder = WebApplication.CreateBuilder(args); 2var app = builder.Build(); 3 4app.MapGet("/file", () => 5{ 6 var filePath = "/usercode/FILESYSTEM/MyTodoApp/todos.txt"; 7 var contentType = "text/plain"; 8 return Results.File(filePath, contentType, "todos.txt"); 9}); 10 11app.Run();

This code maps the /file route to a method that returns the file using the Results.File method. This method sends the specified file with a given content type and filename. This setup allows a user to visit /file and download the todos.txt file from the server.

Returning Binary Data

There may be cases where you need to send binary data, such as images or other non-text files. The Results.Bytes method is useful for this purpose. Here’s how to set up an endpoint to return byte data:

C#
1using System.Text; 2 3var builder = WebApplication.CreateBuilder(args); 4var app = builder.Build(); 5 6app.MapGet("/bytes", () => 7{ 8 var todos = "1. Learn ASP.NET Core\n2. Build a web application"; 9 var bytes = Encoding.UTF8.GetBytes(todos); 10 return Results.Bytes(bytes, "application/octet-stream", "todos.bin"); 11}); 12 13app.Run();

This code maps the /bytes route to a method that converts a string into a byte array and returns it using the Results.Bytes method with a specified content type and filename. This setup enables users to visit /bytes and download the todos.bin file, which contains the To-Dos in a binary format.

Sending Data Asynchronously

For scenarios where you need to send a stream of data, perhaps for large datasets or data generated on the fly, use the Results.Stream method. Here’s how to set up an endpoint to return a data stream:

C#
1var builder = WebApplication.CreateBuilder(args); 2var app = builder.Build(); 3 4app.MapGet("/stream", () => 5{ 6 var stream = new MemoryStream(); 7 var writer = new StreamWriter(stream); 8 writer.Write("1. Learn ASP.NET Core\n2. Build a web application"); 9 writer.Flush(); 10 stream.Position = 0; 11 return Results.Stream(stream, "application/octet-stream", "todos.txt"); 12}); 13 14app.Run();

This code maps the /stream route to a method that writes data to a memory stream and returns it using the Results.Stream method with a specified content type and filename. This endpoint allows users to visit /stream and download the todos.txt file, streamed directly from memory.

At the HTTP level, the response uses the Transfer-Encoding header with the value chunked. The server keeps the connection open and sends data in chunks, ending with a zero-sized chunk to indicate that all data has been sent and the connection can be closed.

Summary

In this lesson, you learned how to return different types of data from an API endpoint using ASP.NET Core Minimal APIs. We covered returning files using Results.File, returning binary data using Results.Bytes, and sending data asynchronously using Results.Stream. These techniques enhance your ability to create versatile and robust APIs that can handle a variety of data requirements. Well done! Your newfound skills will be invaluable as you tackle more complex projects in the future.

Enjoy this lesson? Now it's time to practice with Cosmo!
Practice is how you turn knowledge into actual skills.