aspnetcore/tutorials/min-web-api.md
By Rick Anderson and Tom Dykstra
:::moniker range=">= aspnetcore-9.0"
Minimal APIs are architected to create HTTP APIs with minimal dependencies. They're ideal for microservices and apps that want to include only the minimum files, features, and dependencies in ASP.NET Core.
This tutorial teaches the basics of building a Minimal API with ASP.NET Core. Another approach to creating APIs in ASP.NET Core is to use controllers. For help with choosing between Minimal APIs and controller-based APIs, see xref:fundamentals/apis. For a tutorial on creating an API project based on controllers that contains more features, see Create a web API.
This tutorial creates the following API:
| API | Description | Request body | Response body |
|---|---|---|---|
GET /todoitems | Get all to-do items | None | Array of to-do items |
GET /todoitems/complete | Get completed to-do items | None | Array of to-do items |
GET /todoitems/{id} | Get an item by ID | None | To-do item |
POST /todoitems | Add a new item | To-do item | To-do item |
PUT /todoitems/{id} | Update an existing item | To-do item | None |
PATCH /todoitems/{id} | Partially update an item | Partial to-do item | None |
DELETE /todoitems/{id} | Delete an item | None | None |
Start Visual Studio 2022 and select Create a new project.
In the Create a new project dialog:
Empty in the Search for templates search box.Name the project TodoApi and select Next.
In the Additional information dialog:
Open the integrated terminal.
Change directories (cd) to the folder that will contain the project folder.
Run the following commands:
dotnet new web -o TodoApi
cd TodoApi
code -r ../TodoApi
When a dialog box asks if you want to trust the authors, select Yes.
When a dialog box asks if you want to add required assets to the project, select Yes.
The preceding commands create a new web Minimal API project and open it in Visual Studio Code.
The Program.cs file contains the following code:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todo/Program.cs" id="snippet_min":::
The preceding code:
/ that returns Hello World!.Press Ctrl+F5 to run without the debugger.
Visual Studio launches the Kestrel web server and opens a browser window.
Hello World! is displayed in the browser. The Program.cs file contains a minimal but complete app.
Close the browser window.
In Visual Studio Code, press <kbd>Ctrl</kbd>+<kbd>F5</kbd> (Windows) or <kbd>control</kbd>+<kbd>F5</kbd> (macOS) to run the app without debugging.
The default browser launches with the following URL: https://localhost:<port> where <port> is the randomly generated port number.
Close the browser window.
In Visual Studio Code, from the Run menu, select Stop Debugging or press <kbd>Shift</kbd>+<kbd>F5</kbd> to stop the app.
NuGet packages must be added to support the database and diagnostics used in this tutorial.
Microsoft.EntityFrameworkCore.InMemory.Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore package.Run the following commands:
dotnet add package Microsoft.EntityFrameworkCore.InMemory
dotnet add package Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore
Todo.cs with the following code::::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/Todo.cs":::
The preceding code creates the model for this app. A model is a class that represents data that the app manages.
TodoDb.cs with the following code::::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/TodoDb.cs":::
The preceding code defines the database context, which is the main class that coordinates Entity Framework functionality for a data model. This class derives from the xref:Microsoft.EntityFrameworkCore.DbContext?displayProperty=fullName class.
Program.cs file with the following code:The following highlighted code adds the database context to the dependency injection (DI) container and enables displaying database-related exceptions:
The DI container provides access to the database context and other services.
This tutorial uses Endpoints Explorer and .http files to test the API.
There are many available web API testing tools to choose from, and you can follow this tutorial's introductory API test steps with your own preferred tool.
This tutorial utilizes the .NET package NSwag.AspNetCore, which integrates Swagger tools for generating a testing UI adhering to the OpenAPI specification:
For more information on using OpenAPI and NSwag with ASP.NET, see xref:tutorials/web-api-help-pages-using-swagger.
Run the following command:
dotnet add package NSwag.AspNetCore
The previous command adds the NSwag.AspNetCore package, which contains tools to generate Swagger documents and UI.
In Program.cs add the following highlighted code before app is defined in line var app = builder.Build();
In the previous code:
builder.Services.AddEndpointsApiExplorer();: Enables the API Explorer, which is a service that provides metadata about the HTTP API. The API Explorer is used by Swagger to generate the Swagger document.
builder.Services.AddOpenApiDocument(config => {...});: Adds the Swagger OpenAPI document generator to the application services and configures it to provide more information about the API, such as its title and version. For information on providing more robust API details, see xref:tutorials/get-started-with-nswag#customize-api-documentation
Add the following highlighted code to the next line after app is defined in line var app = builder.Build();
The previous code enables the Swagger middleware for serving the generated JSON document and the Swagger UI. Swagger is only enabled in a development environment. Enabling Swagger in a production environment could expose potentially sensitive details about the API's structure and implementation.
<a name="post"></a>
The following code in Program.cs creates an HTTP POST endpoint /todoitems that adds data to the in-memory database:
Run the app. The browser displays a 404 error because there's no longer a / endpoint.
The POST endpoint will be used to add data to the app.
Select View > Other Windows > Endpoints Explorer.
Right-click the POST endpoint and select Generate request.
A new file is created in the project folder named TodoApi.http, with contents similar to the following example:
@TodoApi_HostAddress = https://localhost:7031
POST {{TodoApi_HostAddress}}/todoitems
###
###) line is a request delimiter: what comes after it is for a different request.The POST request needs headers and a body. To define those parts of the request, add the following lines immediately after the POST request line:
Content-Type: application/json
{
"name":"walk dog",
"isComplete":true
}
The preceding code adds a Content-Type header and a JSON request body. The TodoApi.http file should now look like the following example, but with your port number:
@TodoApi_HostAddress = https://localhost:7057
POST {{TodoApi_HostAddress}}/todoitems
Content-Type: application/json
{
"name":"walk dog",
"isComplete":true
}
###
Run the app.
Select the Send request link that is above the POST request line.
The POST request is sent to the app and the response is displayed in the Response pane.
With the app still running, in the browser, navigate to https://localhost:<port>/swagger to display the API testing page generated by Swagger.
On the Swagger API testing page, select Post /todoitems > Try it out.
Note that the Request body field contains a generated example format reflecting the parameters for the API.
In the request body enter JSON for a to-do item, without specifying the optional id:
{
"name":"walk dog",
"isComplete":true
}
Select Execute.
Swagger provides a Responses pane below the Execute button.
Note a few of the useful details:
id was set to 1.HTTP status code was returned, indicating that the request was successfully processed and resulted in the creation of a new resource.The sample app implements several GET endpoints by calling MapGet:
| API | Description | Request body | Response body |
|---|---|---|---|
GET /todoitems | Get all to-do items | None | Array of to-do items |
GET /todoitems/complete | Get all completed to-do items | None | Array of to-do items |
GET /todoitems/{id} | Get an item by ID | None | To-do item |
Test the app by calling the GET endpoints from a browser or by using Endpoints Explorer. The following steps are for Endpoints Explorer.
In Endpoints Explorer, right-click the first GET endpoint, and select Generate request.
The following content is added to the TodoApi.http file:
GET {{TodoApi_HostAddress}}/todoitems
###
Select the Send request link that is above the new GET request line.
The GET request is sent to the app and the response is displayed in the Response pane.
The response body is similar to the following JSON:
[
{
"id": 1,
"name": "walk dog",
"isComplete": true
}
]
In Endpoints Explorer, right-click the /todoitems/{id} GET endpoint and select Generate request.
The following content is added to the TodoApi.http file:
GET {{TodoApi_HostAddress}}/todoitems/{id}
###
Replace {id} with 1.
Select the Send request link that is above the new GET request line.
The GET request is sent to the app and the response is displayed in the Response pane.
The response body is similar to the following JSON:
{
"id": 1,
"name": "walk dog",
"isComplete": true
}
Test the app by calling the endpoints from a browser or Swagger.
In Swagger select GET /todoitems > Try it out > Execute.
Alternatively, call GET /todoitems from a browser by entering the URI http://localhost:<port>/todoitems. For example, http://localhost:5001/todoitems
The call to GET /todoitems produces a response similar to the following:
[
{
"id": 1,
"name": "walk dog",
"isComplete": true
}
]
Call GET /todoitems/{id} in Swagger to return data from a specific id:
1 and select Execute.Alternatively, call GET /todoitems from a browser by entering the URI https://localhost:<port>/todoitems/1. For example, https://localhost:5001/todoitems/1
The response is similar to the following:
{
"id": 1,
"name": "walk dog",
"isComplete": true
}
This app uses an in-memory database. If the app is restarted, the GET request doesn't return any data. If no data is returned, POST data to the app and try the GET request again.
ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. The response code for this return type is 200 OK, assuming there are no unhandled exceptions. Unhandled exceptions are translated into 5xx errors.
The return types can represent a wide range of HTTP status codes. For example, GET /todoitems/{id} can return two different status values:
item results in an HTTP 200 response.The sample app implements a single PUT endpoint using MapPut:
This method is similar to the MapPost method, except it uses HTTP PUT. A successful response returns 204 (No Content). According to the HTTP specification, a PUT request requires the client to send the entire updated entity, not just the changes. To support partial updates, use HTTP PATCH.
This sample uses an in-memory database that must be initialized each time the app is started. There must be an item in the database before you make a PUT call. Call GET to ensure there's an item in the database before making a PUT call.
Update the to-do item that has Id = 1 and set its name to "feed fish".
In Endpoints Explorer, right-click the PUT endpoint, and select Generate request.
The following content is added to the TodoApi.http file:
PUT {{TodoApi_HostAddress}}/todoitems/{id}
###
In the PUT request line, replace {id} with 1.
Add the following lines immediately after the PUT request line:
Content-Type: application/json
{
"id": 1,
"name": "feed fish",
"isComplete": false
}
The preceding code adds a Content-Type header and a JSON request body.
Select the Send request link that is above the new PUT request line.
The PUT request is sent to the app and the response is displayed in the Response pane. The response body is empty, and the status code is 204.
Use Swagger to send a PUT request:
Select Put /todoitems/{id} > Try it out.
Set the id field to 1.
Set the request body to the following JSON:
{
"id": 1,
"name": "feed fish",
"isComplete": false
}
Select Execute.
Create a file named TodoPatchDto.cs with the following code:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todo/TodoPatchDto.cs":::
The TodoPatchDto class uses nullable properties (string? and bool?) to distinguish between a field that wasn't provided in the request versus a field explicitly set to a value.
The sample app implements a single PATCH endpoint using MapPatch:
This method is similar to the MapPut method, except it uses HTTP PATCH and only updates the fields provided in the request. A successful response returns 204 (No Content). According to the HTTP specification, a PATCH request enables partial updates, allowing clients to send only the fields that need to be changed.
The PATCH endpoint uses a TodoPatchDto class with nullable properties to properly handle partial updates. Using nullable properties allows the endpoint to distinguish between a field that wasn't provided (null) versus a field explicitly set to a value (including false for boolean fields). Without nullable properties, a non-nullable bool would default to false, potentially overwriting an existing true value when that field wasn't included in the request.
[!NOTE] PATCH operations allow partial updates to resources. For more advanced partial updates using JSON Patch documents, see xref:web-api/jsonpatch.
This sample uses an in-memory database that must be initialized each time the app is started. There must be an item in the database before you make a PATCH call. Call GET to ensure there's an item in the database before making a PATCH call.
Update only the name property of the to-do item that has Id = 1 and set its name to "run errands".
In Endpoints Explorer, right-click the PATCH endpoint, and select Generate request.
The following content is added to the TodoApi.http file:
PATCH {{TodoApi_HostAddress}}/todoitems/{id}
###
In the PATCH request line, replace {id} with 1.
Add the following lines immediately after the PATCH request line:
Content-Type: application/json
{
"name": "run errands"
}
The preceding code adds a Content-Type header and a JSON request body with only the field to update.
Select the Send request link that is above the new PATCH request line.
The PATCH request is sent to the app and the response is displayed in the Response pane. The response body is empty, and the status code is 204.
Use Swagger to send a PATCH request:
Select Patch /todoitems/{id} > Try it out.
Set the id field to 1.
Set the request body to the following JSON:
{
"name": "run errands"
}
Select Execute.
The sample app implements a single DELETE endpoint using MapDelete:
In Endpoints Explorer, right-click the DELETE endpoint and select Generate request.
A DELETE request is added to TodoApi.http.
Replace {id} in the DELETE request line with 1. The DELETE request should look like the following example:
DELETE {{TodoApi_HostAddress}}/todoitems/1
###
Select the Send request link for the DELETE request.
The DELETE request is sent to the app and the response is displayed in the Response pane. The response body is empty, and the status code is 204.
Use Swagger to send a DELETE request:
Select DELETE /todoitems/{id} > Try it out.
Set the ID field to 1 and select Execute.
The DELETE request is sent to the app and the response is displayed in the Responses pane. The response body is empty, and the Server response status code is 204.
The sample app code repeats the todoitems URL prefix each time it sets up an endpoint. APIs often have groups of endpoints with a common URL prefix, and the xref:Microsoft.AspNetCore.Builder.EndpointRouteBuilderExtensions.MapGroup%2A method is available to help organize such groups. It reduces repetitive code and allows for customizing entire groups of endpoints with a single call to methods like xref:Microsoft.AspNetCore.Builder.AuthorizationEndpointConventionBuilderExtensions.RequireAuthorization%2A and xref:Microsoft.AspNetCore.Builder.RoutingEndpointConventionBuilderExtensions.WithMetadata%2A.
Replace the contents of Program.cs with the following code:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/Program.cs" id="snippet_all":::
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup_SwaggerVersion/Program.cs" id="snippet_all":::
The preceding code has the following changes:
var todoItems = app.MapGroup("/todoitems"); to set up the group using the URL prefix /todoitems.app.Map<HttpVerb> methods to todoItems.Map<HttpVerb>./todoitems from the Map<HttpVerb> method calls.Test the endpoints to verify that they work the same.
Returning xref:Microsoft.AspNetCore.Http.TypedResults rather than xref:Microsoft.AspNetCore.Http.Results has several advantages, including testability and automatically returning the response type metadata for OpenAPI to describe the endpoint. For more information, see TypedResults vs Results.
The Map<HttpVerb> methods can call route handler methods instead of using lambdas. To see an example, update Program.cs with the following code:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoTypedResults/Program.cs" id="snippet_all":::
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoTypedResults_SwaggerVersion/Program.cs" id="snippet_all":::
The Map<HttpVerb> code now calls methods instead of lambdas:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoTypedResults/Program.cs" id="snippet_group":::
These methods return objects that implement xref:Microsoft.AspNetCore.Http.IResult and are defined by xref:Microsoft.AspNetCore.Http.TypedResults:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoTypedResults/Program.cs" id="snippet_handlers":::
Unit tests can call these methods and test that they return the correct type. For example, if the method is GetAllTodos:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoTypedResults/Program.cs" id="snippet_getalltodos":::
Unit test code can verify that an object of type Ok<Todo[]> is returned from the handler method. For example:
public async Task GetAllTodos_ReturnsOkOfTodosResult()
{
// Arrange
var db = CreateDbContext();
// Act
var result = await TodosApi.GetAllTodos(db);
// Assert: Check for the correct returned type
Assert.IsType<Ok<Todo[]>>(result);
}
<a name="over-post-v7"></a>
Currently the sample app exposes the entire Todo object. In production applications, a subset of the model is often used to restrict the data that can be input and returned. There are multiple reasons behind this and security is a major one. The subset of a model is usually referred to as a Data Transfer Object (DTO), input model, or view model. DTO is used in this article.
A DTO can be used to:
To demonstrate the DTO approach, update the Todo class to include a secret field:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoDTO/Todo.cs":::
The secret field needs to be hidden from this app, but an administrative app could choose to expose it.
Verify you can post and get the secret field.
Create a file named TodoItemDTO.cs with the following code:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoDTO/TodoItemDTO.cs":::
Replace the contents of the Program.cs file with the following code to use this DTO model:
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoDTO/Program.cs" id="snippet_all":::
:::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoDTO_SwaggerVersion/Program.cs" id="snippet_all":::
Verify you can post and get all fields except the secret field.
<a name="diff-v7"></a>
If you run into a problem you can't resolve, compare your code to the completed project. View or download completed project (how to download).
Development environment for Minimal API apps. For information about how to handle errors and exceptions, see Handle errors in ASP.NET Core APIs.See xref:fundamentals/minimal-apis
:::moniker-end