Guided: Building and Versioning an OpenAPI-First ASP.NET Core 10 Minimal API

Table of Contents

1. Challenge

   Define an OpenAPI-First Minimal API contract and map endpoints to that contract

   Welcome to the lab: Building and Versioning an OpenAPI-First ASP.NET Core 10 Minimal API

   In this lab, you’ll build a versioned Minimal API in ASP.NET Core 10 using an OpenAPI-First, contract-driven approach. You’ll design and implement a versioned API that supports multiple versions simultaneously, applies precise endpoint metadata, and generates accurate OpenAPI documentation for each version. Along the way, you’ll learn how to evolve an API without breaking existing consumers, a critical skill for production systems used by other teams or external clients. This lab is ideal for .NET developers who want to move to the next level: designing, versioning, and governing APIs with professional discipline. In this first step, you will configure OpenAPI/Swagger generation, define an OpenAPI-First Minimal API contract, implement Minimal API endpoints that conform to the defined contract and explicitly declare response types and status codes. You will start with configuring OpenAPI/Swagger generation in ASP.NET Core 10. Once OpenAPI/Swagger is configured all endpoints will have a standardized contract description that humans and computers can understand. Now that OpenAPI/Swagger generation is configured, you'll define an OpenAPI-First Contract ProductV1. The next task is to create two methods in ProductRepository. These methods search the data repository and return a list of products based on the search criteria. Next, you will implement an endpoint that gets all products and returns appropriate status codes. Finally, you will create an endpoint that searches for a product by a product id number. The endpoint will return a found/not found status code. Now that you’ve configured OpenAPI/Swagger generation, defined a contract, and implemented two endpoints, you’re ready to move to the next step.

2. Challenge

   Implement versioned Minimal API endpoints that support backward compatibility

   In this step, you will configure API versioning services, define multiple API versions, create version-specific route groups, and map endpoints explicitly to versions.

   Next, you will define how the server handles versioning logic for incoming requests. If a client sends a request without a version, the server should automatically treat it as a request for the default version (1.0) instead of returning an error. Minimal APIs use an ApiVersionSet to manage versioning metadata for groups of endpoints. You'll initialize a builder to create a new collection of versioning rules and explicitly declare that this group of endpoints supports Version 1.0. Then, you'll add support for Version 2.0 to the same group. In this task, you will define a base path for multiple related endpoints. The {version:apiVersion} is a special route constraint. It tells the framework to look at the version segment of the URL (/api/v1.0/products) and map it to the API versioning logic. Next, you'll define a specific HTTP GET endpoint for the Version 1.0 products group you created earlier. It maps the root URL (/api/v1.0/products) to a function that retrieves and formats product data. Good job! You have configured API versioning services, defined multiple API versions and created version-specific route groups. Now you can go to the next step to create Version 2.

3. Challenge

   Implement Minimal API Version 2

   In this step, you will create Version 2 Product model and a route group. Then you will implement Version 2 endpoints. By creating a separate ProductV2record, you allow your V2 endpoints to return more data while your V1 endpoints continue usingProductV1. You'll define a Data Transfer Object (DTO) specifically for Version 2.0 of the API.

   You will use a C# Record instead of a class. Records are ideal for APIs because they are:

   • Immutable: The data can't be changed once created (thread-safe).
   • Concise: It automatically generates a constructor, properties, and equality checks in one line.

   Why this matters for Versioning:

   • By creating a separate ProductV2 record, you allow your V2 endpoints to return more data while your V1 endpoints continue using ProductV1.
   • This prevents "breaking changes". Existing applications using V1 won't crash because they are shielded from the new Category field they aren't expecting. Now, you'll configure URL-based API versioning for a specific group of endpoints and ensure that any requests directed to the products feature must specifically target Version 2.0. Next, you will define a specific HTTP GET endpoint for the Version 2.0 products group. It fetches products, applies an optional filter, and transforms the data into Version 2.0 format. Congratulations! Your ASP.NET Core 10 Minimal API is fully built. You can go to the next step to verify that it works.
4. Challenge

   Verify correct behavior of versioned Minimal API endpoints across multiple API versions

   In this step, you will test the Web API that you built.

   info> If you don't have a Terminal tab already open, click the + sign and select New tab, then select your desired tab from the menu. --- Verify that the application and OpenAPI/Swagger is working in the lab environment:

   1. Inside the Terminal tab click the Run button.
   2. Navigate to {{localhost:5000}}/swagger.
   3. Verify that you see three HTTP GET endpoints of ProductCatalogApi. --- Now that you have verified that OpenAPI/Swagger is setup correctly, you'll verify that Version 1 and Version 2 return the appropriate results.

   ---

   Follow these instructions to verify endpoint behavior accross both versions:

   1. Invoke the URL {{localhost:5000}}/api/v1/products for Version 1.
   2. Verify that the endpoint returns three products (Laptop, Headphones, Desk Chair) with three attributes (id, name, price).
   3. Invoke the URL {{localhost:5000}}/api/v2/products for Version 2.
   4. Verify that the endpoint returns three products (Laptop, Headphones, Desk Chair) with four attributes (id, name, price, category).
   5. Invoke the URL {{localhost:5000}}/api/products without specifying a version.
   6. Verify that the endpoint returns three products (Laptop, Headphones, Desk Chair) with three attributes (id, name, price).

   info> Note: When no version is specified the application should return the default Version 1.

   --- Finally, you'll verify if filtering in Version 2 works correctly. --- Follow these instructions to verify filtering in Version 2:

   1. Invoke the URL {{localhost:5000}}/api/v2/products?category=Electronics.
   2. Verify that the endpoint returns two products (Laptop, Headphones) with four attributes (id, name, price, category). --- Congratulations! You completed Building and Versioning an OpenAPI-First ASP.NET Core 10 Minimal API.

   By completing this lab you developed the following skills:

   • Designed APIs using an OpenAPI-first mindset
   • Implemented Minimal APIs in ASP.NET Core 10
   • Applied endpoint metadata for contract control
   • Implemented API versioning
   • Safely evolved APIs without breaking consumers