In this workshop, we will discuss Minimal APIs.
| Goal | Create a fast, powerful API with .NET 6 |
|---|---|
| What will you learn | Learn the basics of creating a web API that links to a persistent database. |
| What you'll need | .NET 6 and VS Code (For Windows), .NET 6 and VS Code (For macOS) |
| Duration | 1 hour |
| Slides | Powerpoint |
| Author | Katie Savage |
Coming soon...
Create web apps and services with ASP.NET Core, minimal API, and .NET 6
- .NET 6 and VS Code (For Windows)
- .NET 6 and VS Code (For macOS)
- If you already have Visual Studio Code, or another preferred editor, just download the .NET 6 SDK.
- SQLite
In this workshop, use a Minimal API, or Application Programming Interface, to create a dynamic Todo list that you can update, create new items for, mark items as complete, and delete items.
In this segment, you'll learn the basics of what APIs, web APIs, and minimal APIs are and when you will use them.
For more information, click here.
Using the .NET CLI, create a new web application with the command dotnet new web -o TodoApi. Now that you have created your minimal API you can run it. To run your application, navigate to the TodoApi folder and type the command below
TodoApi> dotnet run
Check out your API in action by navigating to http://localhost:5000.
Add a new route to your API by opening the app in your editor and navigating to the Program.cs file. In Program.cs, create new todo route to our api that returns a list items. Add the following MapGet after app.MapGet("/", () => "Hello World!");.
app.MapGet("/todo", () => new { Item = "Water plants", Complete = "false" });This route will return one Todo item.
Learning checklist
- Created a new route /todo
- Used the GET HTTP Request method MapGet
- Configured and implemented OpenAPI and Swagger UI
- Introduced to middleware and dependency injection
In a terminal window, type the following command:
TodoApi> dotnet add package Swashbuckle.AspNetCore --version 6.1.4
To set up Swagger UI, add the following code snippets:
Snippet 1 : Under var builder = WebApplication.CreateBuilder(args);, add the following lines of code:
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Todo API", Description = "Keep track of your tasks", Version = "v1" });
});The AddSwaggerGen method adds information such as title, description, and version to your API.
Snippet 2 : Above app.MapGet("/", () => "Hello World!");, add the following lines of code:
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Todo API V1");
});The preceding code enables middleware to serve the generated OpenAPI description as JSON content, enables middleware to serve the Swagger UI elements, and specifies the OpenAPI description's endpoint.
Go back to your browser where your app is and navigate to this URL https://localhost:5001/swagger.
Learning checklist
- Configured and implemented OpenAPI and Swagger UI
- Introduced to middleware and dependency injection
You just built simple API where you hard coded the results to HTTP method. Now, we are going to step it up a notch and create something dynamic. Instead of returning a static item that is hardcoded to our route, we are going to be creating to-do list we can update, create new items, mark an item as complete and delete an item.
Our to-do APIs is going to:
- Create a new item.
- Return a specific item on a list.
- Update an existing item.
- Delete an item.
class TodoItem
{
public int Id { get; set; }
public string? Item { get; set; }
public bool IsComplete { get; set; }
}Entity Framework is a code library that enables the transfer of data stored in relational database tables(E.g. SQLite and MySQL, SQL server etc) into objects that are more commonly used in application code. In your terminal execute the following:
TodoApi>dotnet add package Microsoft.EntityFrameworkCore.InMemory --version 6.0
Add using Microsoft.EntityFrameworkCore; to the top of your Program.cs file.
Add the following code snippets
Snippet 1 : Below the TodoItem create a TodoDb class
class TodoDb : DbContext
{
public TodoDb(DbContextOptions options) : base(options) { }
public DbSet<TodoItem> Todos { get; set; }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
optionsBuilder.UseInMemoryDatabase("Todos");
}
}Snippet 2 : Before AddSwaggerGen services we configured earlier, add the code snippet below.
builder.Services.AddDbContext<TodoDb>(options => options.UseInMemoryDatabase("items"));Return a list of items To read from a list of items in the todo list replace the "/todo" route with the "/todos" route below.
app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync());Go back your browser and navigate to https://localhost:5001/swagger click on the GET/todos button and you will see the list is empty under Response body.
Let's POST new tasks to the todos list. Below app.MapGet you create earlier.
app.MapPost("/todos", async (TodoDb db, TodoItem todo) =>
{
await db.Todos.AddAsync(todo);
await db.SaveChangesAsync();
return Results.Created($"/todo/{todo.Id}", todo);
});Go back to Swagger and now you should see POST/todos. To add new items to the todo list:
- Click on POST /todos
- Click on Try it out
- Update id, item, and isComplete
- Click Execute
To read the items in the list
- Click on GET/todos
- Click on Try it out
- Click `Execute
- The Response body will include the items just added.
To GET an item by id add the code below app.MapPost route created earlier
app.MapGet("/todos/{id}", async (TodoDb db, int id) => await db.Todos.FindAsync(id));To update an existing item add the code below GET /todos/{id} route we created above.
app.MapPut("/todos/{id}", async ( TodoDb db, TodoItem updateTodo ,int id) =>
{
var todo = await db.Todos.FindAsync(id);
if (todo is null) return NotFound();
todo.Item = updateTodo.Item;
todo.IsComplete = updateTodo.IsComplete;
await db.SaveChangesAsync();
return Results.NoContent();
});- Click on PUT/todos/{id}
- Click on Try it out
- In the id text box enter 2
- Update Request body paste the JSON below and update isComplete to true.
{
"id": 2,
"item": "Water plants",
"isComplete": false
}- Click Execute
To delete an existing item add the code below PUT/todos/{id} we created above.
app.MapDelete("/todos/{id}", async (TodoDb db, int id) =>
{
var todo = await db.Todos.FindAsync(id);
if (todo is null)
{
return NotFound();
}
db.Todos.Remove(todo);
await db.SaveChangesAsync();
return Results.Ok();
});Now, try deleting an item.
Learning checklist:
- Add model class and database context
- CRUD methods (GET, POST, PUT, DELETE)
- Configured routing and returned values
Link: Create Read Update Delete
We just learned how to build a basic CRUD application with an in-memory database. Now, we are going to step it up notch and work with a persistent database. Meaning your data will be saved even after you shut down your application.
Install the following tools and packages
TodoApi>dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 6.0
TodoApi>dotnet tool install --global dotnet-ef
TodoApi>dotnet add package Microsoft.EntityFrameworkCore.Design --version 6.0
In order to enable database creation they are couple of steps we need to complete:
- Set the database connection string.
- Migrate your data model (see below) to a SQLite database. Create a data model
class TodoItem
{
public int Id { get; set; }
public string? Item { get; set; }
public bool IsComplete { get; set; }
}- Create your database and schema
In Program.cs below your app builder var builder = WebApplication.CreateBuilder(args); add a connection string.
var connectionString = builder.Configuration.GetConnectionString("todos") ?? "Data Source=todos.db";Now we are going to replace the in-memory database with a persistent database. Replace your current in-memory database implementation builder.Services.AddDbContext(options => options.UseInMemoryDatabase("items")); in your build services with the SQLite one below:
builder.Services.AddSqlite<TodoDb>(connectionString);With the EF Core migration tool, you can now start your first migration, InitialCreate. In a terminal window, run the migrations command:
dotnet ef migrations add InitialCreate
Now that you have completed the migration, you can use it to create your database and schema. In a terminal window, run the database update command below to apply migrations to a database:
TodoApi> dotnet ef database update
Learn checklist
- Setup SQLite database
- Create a SQLite database
- Perform SQLite CRUD operation from our todo API
Create web apps and services with ASP.NET Core, minimal API, and .NET 6
Be sure to give feedback about this workshop!