Tutorial: creeu una API web amb ASP.NET Core

Aquest tutorial ensenya els conceptes bàsics per crear una API web basada en controladors que utilitza una base de dades. Un altre enfocament per crear API a ASP.NET Core és crear API mínimes . Per obtenir ajuda per triar entre les API mínimes i les API basades en controladors, consulteu Visió general de les API . Per obtenir un tutorial sobre com crear una API mínima, vegeu Tutorial: crear una API mínima amb ASP.NET Core .

Aquest tutorial crea la següent API:

El diagrama següent mostra el disseny de l'aplicació.

La plantilla del projecte crea una WeatherForecastAPI amb suport per a Swagger .

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

/swagger/index.htmlEs mostra la pàgina Swagger . Seleccioneu OBTENIR > Prova-ho > Executar . La pàgina mostra:

• L' ordre Curl per provar l'API WeatherForecast.
• L'URL per provar l'API WeatherForecast.
• El codi de resposta, el cos i les capçaleres.
• Un quadre de llista desplegable amb tipus de suports i el valor i l'esquema d'exemple.

Si la pàgina Swagger no apareix, consulteu aquest problema de GitHub .

Swagger s'utilitza per generar documentació útil i pàgines d'ajuda per a les API web. Aquest tutorial utilitza Swagger per provar l'aplicació. Per obtenir més informació sobre Swagger, consulteu la documentació de l'API web ASP.NET Core amb Swagger/OpenAPI .

Copieu i enganxeu l' URL de sol·licitud al navegador: https://localhost:<port>/weatherforecast

Es retorna un JSON semblant a l'exemple següent:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Un model és un conjunt de classes que representen les dades que gestiona l'aplicació. El model d'aquesta aplicació és la TodoItemclasse.

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

La Idpropietat funciona com a clau única en una base de dades relacional.

Les classes model poden anar a qualsevol part del projecte, però la Modelscarpeta s'utilitza per convenció.

El context de la base de dades és la classe principal que coordina la funcionalitat de l'Entity Framework per a un model de dades. Aquesta classe es crea derivant de la classe Microsoft.EntityFrameworkCore.DbContext .

• Introduïu el codi següent:

  C# Còpia

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

A ASP.NET Core, els serveis com el context de la base de dades s'han de registrar amb el contenidor d'injecció de dependències (DI) . El contenidor proporciona el servei als controladors.

Actualitzeu Program.csamb el següent codi destacat:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

El codi anterior:

• Afegeix usingdirectives.
• Afegeix el context de la base de dades al contenidor DI.
• Especifica que el context de la base de dades utilitzarà una base de dades en memòria.

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design -v 7.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design -v 7.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer -v 7.0.0
dotnet tool uninstall -g dotnet-aspnet-codegenerator
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet tool update -g dotnet-aspnet-codegenerator

dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

El codi generat:

• Marca la classe amb l' [ApiController]atribut. Aquest atribut indica que el controlador respon a les sol·licituds de l'API web. Per obtenir informació sobre comportaments específics que activa l'atribut, vegeu Crear API web amb ASP.NET Core .
• Utilitza DI per injectar el context de la base de dades ( TodoContext) al controlador. El context de la base de dades s'utilitza en cadascun dels mètodes CRUD del controlador.

Les plantilles ASP.NET Core per a:

• Els controladors amb vistes inclouen [action]a la plantilla de ruta.
• Els controladors de l'API no s'inclouen [action]a la plantilla de ruta.

Quan el [action]testimoni no es troba a la plantilla de ruta, el nom de l'acció (nom del mètode) no s'inclou al punt final. És a dir, el nom del mètode associat a l'acció no s'utilitza a la ruta coincident.

Actualitzeu la declaració de retorn a la PostTodoItemper utilitzar l' operador nameof :

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

El codi anterior és un HTTP POSTmètode, tal com indica l' [HttpPost]atribut. El mètode obté el valor del TodoItemcos de la sol·licitud HTTP.

Per obtenir més informació, vegeu Encaminament d'atributs amb atributs Http[Verb] .

El mètode CreatedAtAction :

• Retorna un codi d'estat HTTP 201 si té èxit. HTTP 201és la resposta estàndard per a un HTTP POSTmètode que crea un recurs nou al servidor.
• Afegeix una capçalera Ubicació a la resposta. La Locationcapçalera especifica l' URI de l'element de tasca que s'acaba de crear. Per obtenir més informació, vegeu 10.2.2 201 Creat .
• Fa referència a l' GetTodoItemacció per crear l' LocationURI de la capçalera. La paraula clau C# nameofs'utilitza per evitar codificar el nom de l'acció a la CreatedAtActiontrucada.

• Premeu Ctrl+F5 per executar l'aplicació.

• A la finestra del navegador Swagger, seleccioneu POST /api/TodoItems i, a continuació, seleccioneu Prova-ho .

• A la finestra d'entrada del cos de la sol·licitud , actualitzeu el JSON. Per exemple,

  JSON Còpia

  {
    "name": "walk dog",
    "isComplete": true
  }
  

• Seleccioneu Executar

  

A la publicació POST anterior, la interfície d'usuari de Swagger mostra la capçalera d'ubicació sota Capçaleres de resposta . Per exemple, location: https://localhost:7260/api/TodoItems/1. La capçalera de la ubicació mostra l'URI del recurs creat.

Per provar la capçalera de la ubicació:

• A la finestra del navegador Swagger, seleccioneu GET /api/TodoItems/{id} i, a continuació, seleccioneu Prova-ho .

• Introduïu 1al idquadre d'entrada i, a continuació, seleccioneu Executar .

  

S'implementen dos punts finals GET:

• GET /api/todoitems
• GET /api/todoitems/{id}

L'apartat anterior mostrava un exemple de la /api/todoitems/{id}ruta.

Seguiu les instruccions POST per afegir un altre ítem i, a continuació, proveu la /api/todoitemsruta amb Swagger.

Aquesta aplicació utilitza una base de dades a la memòria. Si l'aplicació s'atura i s'inicia, la sol·licitud GET anterior no retornarà cap dada. Si no es retornen dades, POST les dades a l'aplicació.

L' [HttpGet]atribut denota un mètode que respon a una HTTP GETsol·licitud. El camí de l'URL per a cada mètode es construeix de la següent manera:

• Comenceu amb la cadena de plantilla a l'atribut del controlador Route:

  C# Còpia

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Substituïu [controller]-lo pel nom del controlador, que per convenció és el nom de la classe del controlador menys el sufix "Controlador". Per a aquesta mostra, el nom de la classe del controlador és Controlador TodoItems , de manera que el nom del controlador és "TodoItems". L'encaminament ASP.NET Core no distingeix entre majúscules i minúscules.

• Si l' [HttpGet]atribut té una plantilla de ruta (per exemple, [HttpGet("products")]), afegiu-la a la ruta. Aquesta mostra no utilitza cap plantilla. Per obtenir més informació, vegeu Encaminament d'atributs amb atributs Http[Verb] .

En el GetTodoItemmètode següent, "{id}"és una variable de marcador de posició per a l'identificador únic de l'element pendent. Quan GetTodoItems'invoca, el valor de "{id}"a l'URL es proporciona al mètode en el seu idparàmetre.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

El tipus de retorn dels mètodes GetTodoItemsi és el tipus ActionResult<T> . ASP.NET Core serialitza automàticament l'objecte a JSON i escriu el JSON al cos del missatge de resposta. El codi de resposta per a aquest tipus de retorn és 200 OK , suposant que no hi ha excepcions no gestionades. Les excepcions no gestionades es tradueixen en errors 5xx.GetTodoItem

ActionResultEls tipus de retorn poden representar una àmplia gamma de codis d'estat HTTP. Per exemple, GetTodoItempot retornar dos valors d'estat diferents:

• Si cap element coincideix amb l'ID sol·licitat, el mètode retorna un codi d'error d'estat 404 No trobat .
• En cas contrari, el mètode retorna 200 amb un cos de resposta JSON. El retorn itemresulta en una HTTP 200resposta.

Examineu el PutTodoItemmètode:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItemés similar a PostTodoItem, excepte que utilitza HTTP PUT. La resposta és 204 (Sense contingut) . Segons l'especificació HTTP, una PUTsol·licitud requereix que el client enviï tota l'entitat actualitzada, no només els canvis. Per admetre actualitzacions parcials, utilitzeu HTTP PATCH .

Aquesta mostra utilitza una base de dades a la memòria que s'ha d'inicialitzar cada vegada que s'inicia l'aplicació. Hi ha d'haver un element a la base de dades abans de fer una trucada PUT. Truqueu a GET per assegurar-vos que hi ha un element a la base de dades abans de fer una trucada PUT.

Amb la interfície d'usuari de Swagger, utilitzeu el botó PUT per actualitzar el TodoItemque té Id = 1 i establir-ne el nom a "feed fish". Tingueu en compte que la resposta és HTTP 204 No Content.

Examineu el DeleteTodoItemmètode:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Utilitzeu la interfície d'usuari de Swagger per suprimir el TodoItemque té Id = 1. Tingueu en compte que la resposta és HTTP 204 No Content.

Hi ha moltes altres eines que es poden utilitzar per provar les API web, per exemple:

• Visual Studio Endpoints Explorer i fitxers .http
• http-repl
• Carter
• rínxol . Swagger utilitza curli mostra les curlordres que envia.
• violinista

Per a més informació, consulteu:

• Tutorial d'API mínima: prova amb fitxers .http i Endpoints Explorer
• Prova les API amb Postman
• Instal·leu i proveu les API ambhttp-repl

Actualment, l'aplicació de mostra exposa tot l' TodoItemobjecte. Les aplicacions de producció solen limitar les dades que s'introdueixen i es retornen mitjançant un subconjunt del model. Hi ha diverses raons darrere d'això, i la seguretat és una de les principals. El subconjunt d'un model es coneix normalment com a objecte de transferència de dades (DTO), model d'entrada o model de vista. DTO s'utilitza en aquest tutorial.

Un DTO es pot utilitzar per:

• Evita la publicació excessiva.
• Amaga les propietats que els clients no han de veure.
• Omet algunes propietats per reduir la mida de la càrrega útil.
• Aplaneu els gràfics d'objectes que contenen objectes imbricats. Els gràfics d'objectes aplanats poden ser més convenients per als clients.

Per demostrar l'enfocament DTO, actualitzeu la TodoItemclasse per incloure un camp secret:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

El camp secret s'ha d'ocultar d'aquesta aplicació, però una aplicació administrativa podria optar per exposar-lo.

Verifiqueu que podeu publicar i obtenir el camp secret.

Creeu un model DTO:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Actualitzeu TodoItemsControllerper utilitzar TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Verifiqueu que no podeu publicar ni obtenir el camp secret.

Vegeu el tutorial: crida a una API web ASP.NET Core amb JavaScript .

Vegeu Vídeo: Sèrie per a principiants a: API web .

Consulteu els vídeos i l'article de The Reliable Web App Pattern for.NET de YouTube per obtenir orientació sobre com crear una aplicació ASP.NET Core moderna, fiable, rendible, provable, rendible i escalable, ja sigui des de zero o refactoritzant una aplicació existent.

ASP.NET Core Identity afegeix la funcionalitat d'inici de sessió de la interfície d'usuari (UI) a les aplicacions web ASP.NET Core. Per protegir les API web i els SPA, utilitzeu una de les opcions següents:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Servidor d'identitats Duende

Duende Identity Server és un marc OpenID Connect i OAuth 2.0 per a ASP.NET Core. Duende Identity Server habilita les funcions de seguretat següents:

• Autenticació com a servei (AaaS)
• Inici/desactivació únic (SSO) en diversos tipus d'aplicacions
• Control d'accés a les API
• Portal de la Federació

Per obtenir més informació, consulteu la documentació del Duende Identity Server (lloc web de Duende Software) .

Per obtenir informació sobre la implementació a Azure, vegeu Inici ràpid: implementar una aplicació web ASP.NET .

Consulteu o descarregueu el codi de mostra d'aquest tutorial . Vegeu com descarregar .

Per a més informació, consulteu els recursos següents:

• Creeu API web amb ASP.NET Core
• Tutorial: creeu una API mínima amb ASP.NET Core
• Documentació de l'API web ASP.NET Core amb Swagger / OpenAPI
• Pàgines de Razor amb Entity Framework Core a ASP.NET Core - Tutorial 1 de 8
• Enrutament a accions del controlador a ASP.NET Core
• Tipus de retorn d'accions del controlador a l'API web ASP.NET Core
• Desplegueu aplicacions ASP.NET Core a Azure App Service
• Allotjament i implementació d'ASP.NET Core
• Creeu una API web amb ASP.NET Core

This tutorial teaches the basics of building a controller-based web API that uses a database. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help in choosing between minimal APIs and controller-based APIs, see APIs overview. For a tutorial on creating a minimal API, see Tutorial: Create a minimal API with ASP.NET Core.

This tutorial creates the following API:

The following diagram shows the design of the app.

The project template creates a WeatherForecast API with support for Swagger.

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

The Swagger page /swagger/index.html is displayed. Select GET > Try it out > Execute. The page displays:

• The Curl command to test the WeatherForecast API.
• The URL to test the WeatherForecast API.
• The response code, body, and headers.
• A drop-down list box with media types and the example value and schema.

If the Swagger page doesn't appear, see this GitHub issue.

Swagger is used to generate useful documentation and help pages for web APIs. This tutorial focuses on creating a web API. For more information on Swagger, see ASP.NET Core web API documentation with Swagger / OpenAPI.

Copy and paste the Request URL in the browser: https://localhost:<port>/weatherforecast

JSON similar to the following example is returned:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

A model is a set of classes that represent the data that the app manages. The model for this app is the TodoItem class.

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

The database context is the main class that coordinates Entity Framework functionality for a data model. This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

• Enter the following code:

  C# Copy

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. The container provides the service to controllers.

Update Program.cs with the following highlighted code:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

The preceding code:

• Adds using directives.
• Adds the database context to the DI container.
• Specifies that the database context will use an in-memory database.

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design -v 7.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design -v 7.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer -v 7.0.0
dotnet tool uninstall -g dotnet-aspnet-codegenerator
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet tool update -g dotnet-aspnet-codegenerator

dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

The generated code:

• Marks the class with the [ApiController] attribute. This attribute indicates that the controller responds to web API requests. For information about specific behaviors that the attribute enables, see Create web APIs with ASP.NET Core.
• Uses DI to inject the database context (TodoContext) into the controller. The database context is used in each of the CRUD methods in the controller.

The ASP.NET Core templates for:

• Controllers with views include [action] in the route template.
• API controllers don't include [action] in the route template.

When the [action] token isn't in the route template, the action name (method name) isn't included in the endpoint. That is, the action's associated method name isn't used in the matching route.

Update the return statement in the PostTodoItem to use the nameof operator:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the value of the TodoItem from the body of the HTTP request.

For more information, see Attribute routing with Http[Verb] attributes.

The CreatedAtAction method:

• Returns an HTTP 201 status code if successful. HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. For more information, see 10.2.2 201 Created.
• References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

• Press Ctrl+F5 to run the app.

• In the Swagger browser window, select POST /api/TodoItems, and then select Try it out.

• In the Request body input window, update the JSON. For example,

  JSON Copy

  {
    "name": "walk dog",
    "isComplete": true
  }
  

• Select Execute

  

In the preceding POST, the Swagger UI shows the location header under Response headers. For example, location: https://localhost:7260/api/TodoItems/1. The location header shows the URI to the created resource.

To test the location header:

• In the Swagger browser window, select GET /api/TodoItems/{id}, and then select Try it out.

• Enter 1 in the id input box, and then select Execute.

  

Two GET endpoints are implemented:

• GET /api/todoitems
• GET /api/todoitems/{id}

The previous section showed an example of the /api/todoitems/{id} route.

Follow the POST instructions to add another todo item, and then test the /api/todoitems route using Swagger.

This app uses an in-memory database. If the app is stopped and started, the preceding GET request will not return any data. If no data is returned, POST data to the app.

The [HttpGet] attribute denotes a method that responds to an HTTP GET request. The URL path for each method is constructed as follows:

• Start with the template string in the controller's Route attribute:

  C# Copy

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. This sample doesn't use a template. For more information, see Attribute routing with Http[Verb] attributes.

In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. 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.

ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can return two different status values:

• If no item matches the requested ID, the method returns a 404 status NotFound error code.
• Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200 response.

Examine the PutTodoItem method:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. The response is 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.

Using the Swagger UI, use the PUT button to update the TodoItem that has Id = 1 and set its name to "feed fish". Note the response is HTTP 204 No Content.

Examine the DeleteTodoItem method:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Use the Swagger UI to delete the TodoItem that has Id = 1. Note the response is HTTP 204 No Content.

http-repl, Postman, and curl are often used to test API's. Swagger uses curl and shows the curl command it submitted.

For instructions on these tools, see the following links:

• Test APIs with Postman
• Install and test APIs with http-repl

For more information on http-repl, see Test web APIs with the HttpRepl.

Currently the sample app exposes the entire TodoItem object. Production apps typically limit the data that's input and returned using a subset of the model. 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 tutorial.

A DTO may be used to:

• Prevent over-posting.
• Hide properties that clients are not supposed to view.
• Omit some properties in order to reduce payload size.
• Flatten object graphs that contain nested objects. Flattened object graphs can be more convenient for clients.

To demonstrate the DTO approach, update the TodoItem class to include a secret field:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

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 DTO model:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Update the TodoItemsController to use TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Verify you can't post or get the secret field.

See Tutorial: Call an ASP.NET Core web API with JavaScript.

See Video: Beginner's Series to: Web APIs.

See The Reliable Web App Pattern for.NET YouTube videos and article for guidance on creating a modern, reliable, performant, testable, cost-efficient, and scalable ASP.NET Core app, whether from scratch or refactoring an existing app.

ASP.NET Core Identity adds user interface (UI) login functionality to ASP.NET Core web apps. To secure web APIs and SPAs, use one of the following:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. Duende Identity Server enables the following security features:

• Authentication as a Service (AaaS)
• Single sign-on/off (SSO) over multiple application types
• Access control for APIs
• Federation Gateway

For more information, see the Duende Identity Server documentation (Duende Software website).

For information on deploying to Azure, see Quickstart: Deploy an ASP.NET web app.

View or download sample code for this tutorial. See how to download.

For more information, see the following resources:

• Create web APIs with ASP.NET Core
• Tutorial: Create a minimal API with ASP.NET Core
• ASP.NET Core web API documentation with Swagger / OpenAPI
• Razor Pages with Entity Framework Core in ASP.NET Core - Tutorial 1 of 8
• Routing to controller actions in ASP.NET Core
• Controller action return types in ASP.NET Core web API
• Deploy ASP.NET Core apps to Azure App Service
• Host and deploy ASP.NET Core
• Create a web API with ASP.NET Core

This tutorial teaches the basics of building a controller-based web API that uses a database. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help in choosing between minimal APIs and controller-based APIs, see APIs overview. For a tutorial on creating a minimal API, see Tutorial: Create a minimal API with ASP.NET Core.

In this tutorial, you learn how to:

At the end, you have a web API that can manage "to-do" items stored in a database.

This tutorial creates the following API:

The following diagram shows the design of the app.

dotnet add package Microsoft.EntityFrameworkCore.InMemory

The project template creates a WeatherForecast API with support for Swagger.

The Swagger page /swagger/index.html is displayed. Select GET > Try it out > Execute. The page displays:

• The Curl command to test the WeatherForecast API.
• The URL to test the WeatherForecast API.
• The response code, body, and headers.
• A drop-down list box with media types and the example value and schema.

If the Swagger page doesn't appear, see this GitHub issue.

Swagger is used to generate useful documentation and help pages for web APIs. This tutorial focuses on creating a web API. For more information on Swagger, see ASP.NET Core web API documentation with Swagger / OpenAPI.

Copy and paste the Request URL in the browser: https://localhost:<port>/weatherforecast

JSON similar to the following example is returned:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

In Properties\launchSettings.json, update launchUrl from "swagger" to "api/todoitems":

"launchUrl": "api/todoitems",

Because Swagger will be removed, the preceding markup changes the URL that is launched to the GET method of the controller added in the following sections.

A model is a set of classes that represent the data that the app manages. The model for this app is a single TodoItem class.

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

The database context is the main class that coordinates Entity Framework functionality for a data model. This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

• Enter the following code:

  C# Copy

  using Microsoft.EntityFrameworkCore;
  using System.Diagnostics.CodeAnalysis;
  
  namespace TodoApi.Models
  {
      public class TodoContext : DbContext
      {
          public TodoContext(DbContextOptions<TodoContext> options)
              : base(options)
          {
          }
  
          public DbSet<TodoItem> TodoItems { get; set; } = null!;
      }
  }
  

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. The container provides the service to controllers.

Update Program.cs with the following code:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;


var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
//builder.Services.AddSwaggerGen(c =>
//{
//    c.SwaggerDoc("v1", new() { Title = "TodoApi", Version = "v1" });
//});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (builder.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    //app.UseSwagger();
    //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

The preceding code:

• Removes the Swagger calls.
• Removes unused using directives.
• Adds the database context to the DI container.
• Specifies that the database context will use an in-memory database.

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

The generated code:

• Marks the class with the [ApiController] attribute. This attribute indicates that the controller responds to web API requests. For information about specific behaviors that the attribute enables, see Create web APIs with ASP.NET Core.
• Uses DI to inject the database context (TodoContext) into the controller. The database context is used in each of the CRUD methods in the controller.

The ASP.NET Core templates for:

• Controllers with views include [action] in the route template.
• API controllers don't include [action] in the route template.

When the [action] token isn't in the route template, the action name is excluded from the route. That is, the action's associated method name isn't used in the matching route.

Update the return statement in the PostTodoItem to use the nameof operator:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the value of the to-do item from the body of the HTTP request.

For more information, see Attribute routing with Http[Verb] attributes.

The CreatedAtAction method:

• Returns an HTTP 201 status code if successful. HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. For more information, see 10.2.2 201 Created.
• References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

This tutorial uses http-repl to test the web API.

• Run the following command at a command prompt:

  .NET CLI Copy

  dotnet tool install -g Microsoft.dotnet-httprepl
  

  Note

  By default the architecture of the .NET binaries to install represents the currently running OS architecture. To specify a different OS architecture, see dotnet tool install, --arch option. For more information, see GitHub issue dotnet/AspNetCore.Docs #29262.

• If you don't have the .NET 6.0 SDK or runtime installed, install the .NET 6.0 runtime.

• Press Ctrl+F5 to run the app.

• Open a new terminal window, and run the following commands. If your app uses a different port number, replace 5001 in the httprepl command with your port number.

  .NET CLI Copy

  httprepl https://localhost:5001/api/todoitems
  post -h Content-Type=application/json -c "{"name":"walk dog","isComplete":true}"
  

  Here's an example of the output from the command:

  Output Copy

  HTTP/1.1 201 Created
  Content-Type: application/json; charset=utf-8
  Date: Tue, 07 Sep 2021 20:39:47 GMT
  Location: https://localhost:5001/api/TodoItems/1
  Server: Kestrel
  Transfer-Encoding: chunked
  
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

To test the location header, copy and paste it into an httprepl get command.

The following example assumes that you're still in an httprepl session. If you ended the previous httprepl session, replace connect with httprepl in the following commands:

connect https://localhost:5001/api/todoitems/1
get

Here's an example of the output from the command:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:48:10 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "name": "walk dog",
  "isComplete": true
}

Two GET endpoints are implemented:

• GET /api/todoitems
• GET /api/todoitems/{id}

You just saw an example of the /api/todoitems/{id} route. Test the /api/todoitems route:

connect https://localhost:5001/api/todoitems
get

Here's an example of the output from the command:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:59:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

This time, the JSON returned is an array of one item.

This app uses an in-memory database. If the app is stopped and started, the preceding GET request will not return any data. If no data is returned, POST data to the app.

The [HttpGet] attribute denotes a method that responds to an HTTP GET request. The URL path for each method is constructed as follows:

• Start with the template string in the controller's Route attribute:

  C# Copy

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. This sample doesn't use a template. For more information, see Attribute routing with Http[Verb] attributes.

In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. 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.

ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can return two different status values:

• If no item matches the requested ID, the method returns a 404 status NotFound error code.
• Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200 response.

Examine the PutTodoItem method:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. The response is 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.

If you get an error calling PutTodoItem in the following section, call GET to ensure there's an item in the database.

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":

connect https://localhost:5001/api/todoitems/1
put -h Content-Type=application/json -c "{"id":1,"name":"feed fish","isComplete":true}"

Here's an example of the output from the command:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:20:47 GMT
Server: Kestrel

Examine the DeleteTodoItem method:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Delete the to-do item that has Id = 1:

connect https://localhost:5001/api/todoitems/1
delete

Here's an example of the output from the command:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:43:00 GMT
Server: Kestrel

Currently the sample app exposes the entire TodoItem object. Production apps typically limit the data that's input and returned using a subset of the model. 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 tutorial.

A DTO may be used to:

• Prevent over-posting.
• Hide properties that clients are not supposed to view.
• Omit some properties in order to reduce payload size.
• Flatten object graphs that contain nested objects. Flattened object graphs can be more convenient for clients.

To demonstrate the DTO approach, update the TodoItem class to include a secret field:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

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 DTO model:

namespace TodoApi.Models
{
    public class TodoItemDTO
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Update the TodoItemsController to use TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;

        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }

        // GET: api/TodoItems
        [HttpGet]
        public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
        {
            return await _context.TodoItems
                .Select(x => ItemToDTO(x))
                .ToListAsync();
        }

        // GET: api/TodoItems/5
        [HttpGet("{id}")]
        public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            return ItemToDTO(todoItem);
        }
        // PUT: api/TodoItems/5
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPut("{id}")]
        public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
        {
            if (id != todoItemDTO.Id)
            {
                return BadRequest();
            }

            var todoItem = await _context.TodoItems.FindAsync(id);
            if (todoItem == null)
            {
                return NotFound();
            }

            todoItem.Name = todoItemDTO.Name;
            todoItem.IsComplete = todoItemDTO.IsComplete;

            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
            {
                return NotFound();
            }

            return NoContent();
        }
        // POST: api/TodoItems
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPost]
        public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
        {
            var todoItem = new TodoItem
            {
                IsComplete = todoItemDTO.IsComplete,
                Name = todoItemDTO.Name
            };

            _context.TodoItems.Add(todoItem);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetTodoItem),
                new { id = todoItem.Id },
                ItemToDTO(todoItem));
        }

        // DELETE: api/TodoItems/5
        [HttpDelete("{id}")]
        public async Task<IActionResult> DeleteTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            _context.TodoItems.Remove(todoItem);
            await _context.SaveChangesAsync();

            return NoContent();
        }

        private bool TodoItemExists(long id)
        {
            return _context.TodoItems.Any(e => e.Id == id);
        }

        private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
            new TodoItemDTO
            {
                Id = todoItem.Id,
                Name = todoItem.Name,
                IsComplete = todoItem.IsComplete
            };
    }
}

Verify you can't post or get the secret field.

See Tutorial: Call an ASP.NET Core web API with JavaScript.

See Video: Beginner's Series to: Web APIs.

ASP.NET Core Identity adds user interface (UI) login functionality to ASP.NET Core web apps. To secure web APIs and SPAs, use one of the following:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. Duende Identity Server enables the following security features:

• Authentication as a Service (AaaS)
• Single sign-on/off (SSO) over multiple application types
• Access control for APIs
• Federation Gateway

For more information, see the Duende Identity Server documentation (Duende Software website).

For information on deploying to Azure, see Quickstart: Deploy an ASP.NET web app.

View or download sample code for this tutorial. See how to download.

For more information, see the following resources:

• Create web APIs with ASP.NET Core
• Tutorial: Create a minimal API with ASP.NET Core
• ASP.NET Core web API documentation with Swagger / OpenAPI
• Razor Pages with Entity Framework Core in ASP.NET Core - Tutorial 1 of 8
• Routing to controller actions in ASP.NET Core
• Controller action return types in ASP.NET Core web API
• Deploy ASP.NET Core apps to Azure App Service
• Host and deploy ASP.NET Core
• Create a web API with ASP.NET Core

This tutorial teaches the basics of building a controller-based web API that uses a database. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help in choosing between minimal APIs and controller-based APIs, see APIs overview. For a tutorial on creating a minimal API, see Tutorial: Create a minimal API with ASP.NET Core.

In this tutorial, you learn how to:

At the end, you have a web API that can manage "to-do" items stored in a database.

This tutorial creates the following API:

The following diagram shows the design of the app.

dotnet add package Microsoft.EntityFrameworkCore.InMemory

The project template creates a WeatherForecast API with support for Swagger.

The Swagger page /swagger/index.html is displayed. Select GET > Try it out > Execute. The page displays:

• The Curl command to test the WeatherForecast API.
• The URL to test the WeatherForecast API.
• The response code, body, and headers.
• A drop down list box with media types and the example value and schema.

If the Swagger page doesn't appear, see this GitHub issue.

Swagger is used to generate useful documentation and help pages for web APIs. This tutorial focuses on creating a web API. For more information on Swagger, see ASP.NET Core web API documentation with Swagger / OpenAPI.

Copy and paste the Request URL in the browser: https://localhost:<port>/weatherforecast

JSON similar to the following is returned:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

In Properties\launchSettings.json, update launchUrl from "swagger" to "api/todoitems":

"launchUrl": "api/todoitems",

Because Swagger will be removed, the preceding markup changes the URL that is launched to the GET method of the controller added in the following sections.

A model is a set of classes that represent the data that the app manages. The model for this app is a single TodoItem class.

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

The database context is the main class that coordinates Entity Framework functionality for a data model. This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

• Enter the following code:

  C# Copy

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models
  {
      public class TodoContext : DbContext
      {
          public TodoContext(DbContextOptions<TodoContext> options)
              : base(options)
          {
          }
  
          public DbSet<TodoItem> TodoItems { get; set; }
      }
  }
  

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. The container provides the service to controllers.

Update Startup.cs with the following code:

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddDbContext<TodoContext>(opt =>
                                               opt.UseInMemoryDatabase("TodoList"));
            //services.AddSwaggerGen(c =>
            //{
            //    c.SwaggerDoc("v1", new OpenApiInfo { Title = "TodoApi", Version = "v1" });
            //});
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                //app.UseSwagger();
                //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
            }

            app.UseHttpsRedirection();
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

The preceding code:

• Removes the Swagger calls.
• Removes unused using declarations.
• Adds the database context to the DI container.
• Specifies that the database context will use an in-memory database.

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

The generated code:

• Marks the class with the [ApiController] attribute. This attribute indicates that the controller responds to web API requests. For information about specific behaviors that the attribute enables, see Create web APIs with ASP.NET Core.
• Uses DI to inject the database context (TodoContext) into the controller. The database context is used in each of the CRUD methods in the controller.

The ASP.NET Core templates for:

• Controllers with views include [action] in the route template.
• API controllers don't include [action] in the route template.

When the [action] token isn't in the route template, the action name is excluded from the route. That is, the action's associated method name isn't used in the matching route.

Update the return statement in the PostTodoItem to use the nameof operator:

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the value of the to-do item from the body of the HTTP request.

For more information, see Attribute routing with Http[Verb] attributes.

The CreatedAtAction method:

• Returns an HTTP 201 status code if successful. HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. For more information, see 201 Created.
• References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

This tutorial uses Postman to test the web API.

• Install Postman
• Start the web app.
• Start Postman.
• Disable SSL certificate verification:
  • Postman for Windows: Select File > Settings (General tab), disable SSL certificate verification.
  • Postman for macOS: Select Postman > Settings (General tab), disable SSL certificate verification.

    Warning

    Re-enable SSL certificate verification after testing the controller.

• Create a new request.

• Set the HTTP method to POST.

• Set the URI to https://localhost:<port>/api/todoitems. For example, https://localhost:5001/api/todoitems.

• Select the Body tab.

• Select the raw radio button.

• Set the type to JSON (application/json).

• In the request body enter JSON for a to-do item:

  JSON Copy

  {
    "name":"walk dog",
    "isComplete":true
  }
  

• Select Send.

  

The location header URI can be tested in the browser. Copy and paste the location header URI into the browser.

To test in Postman:

• Select the Headers tab in the Response pane.

• Copy the Location header value:

  

• Set the HTTP method to GET.

• Set the URI to https://localhost:<port>/api/todoitems/1. For example, https://localhost:5001/api/todoitems/1.

• Select Send.

Two GET endpoints are implemented:

• GET /api/todoitems
• GET /api/todoitems/{id}

Test the app by calling the two endpoints from a browser or Postman. For example:

• https://localhost:5001/api/todoitems
• https://localhost:5001/api/todoitems/1

A response similar to the following is produced by the call to GetTodoItems:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

• Create a new request.
• Set the HTTP method to GET.
• Set the request URI to https://localhost:<port>/api/todoitems. For example, https://localhost:5001/api/todoitems.
• Set Two pane view in Postman.
• Select Send.

This app uses an in-memory database. If the app is stopped and started, the preceding GET request will not return any data. If no data is returned, POST data to the app.

The [HttpGet] attribute denotes a method that responds to an HTTP GET request. The URL path for each method is constructed as follows:

• Start with the template string in the controller's Route attribute:

  C# Copy

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  {
      private readonly TodoContext _context;
  
      public TodoItemsController(TodoContext context)
      {
          _context = context;
      }
  

• Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. This sample doesn't use a template. For more information, see Attribute routing with Http[Verb] attributes.

In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. 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.

ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can return two different status values:

• If no item matches the requested ID, the method returns a 404 status NotFound error code.
• Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200 response.

Examine the PutTodoItem method:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. The response is 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.

If you get an error calling PutTodoItem, call GET to ensure there's an item in the database.

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":

  {
    "Id":1,
    "name":"feed fish",
    "isComplete":true
  }

The following image shows the Postman update:

Examine the DeleteTodoItem method:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Use Postman to delete a to-do item:

• Set the method to DELETE.
• Set the URI of the object to delete (for example https://localhost:5001/api/todoitems/1).
• Select Send.

Currently the sample app exposes the entire TodoItem object. Production apps typically limit the data that's input and returned using a subset of the model. 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 may be used to:

• Prevent over-posting.
• Hide properties that clients are not supposed to view.
• Omit some properties in order to reduce payload size.
• Flatten object graphs that contain nested objects. Flattened object graphs can be more convenient for clients.

To demonstrate the DTO approach, update the TodoItem class to include a secret field:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
        public string Secret { get; set; }
    }
}

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 DTO model:

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Update the TodoItemsController to use TodoItemDTO:

// GET: api/TodoItems
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
{
    return await _context.TodoItems
        .Select(x => ItemToDTO(x))
        .ToListAsync();
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

[HttpPut("{id}")]
public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
{
    if (id != todoItemDTO.Id)
    {
        return BadRequest();
    }

    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    todoItem.Name = todoItemDTO.Name;
    todoItem.IsComplete = todoItemDTO.IsComplete;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
    {
        return NotFound();
    }

    return NoContent();
}

[HttpPost]
public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
{
    var todoItem = new TodoItem
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    return CreatedAtAction(
        nameof(GetTodoItem),
        new { id = todoItem.Id },
        ItemToDTO(todoItem));
}

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

private bool TodoItemExists(long id) =>
     _context.TodoItems.Any(e => e.Id == id);

private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
    new TodoItemDTO
    {
        Id = todoItem.Id,
        Name = todoItem.Name,
        IsComplete = todoItem.IsComplete
    };

Verify you can't post or get the secret field.

See Tutorial: Call an ASP.NET Core web API with JavaScript.

ASP.NET Core Identity adds user interface (UI) login functionality to ASP.NET Core web apps. To secure web APIs and SPAs, use one of the following:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. Duende Identity Server enables the following security features:

• Authentication as a Service (AaaS)
• Single sign-on/off (SSO) over multiple application types
• Access control for APIs
• Federation Gateway

For more information, see the Duende Identity Server documentation (Duende Software website).

For information on deploying to Azure, see Quickstart: Deploy an ASP.NET web app.

View or download sample code for this tutorial. See how to download.

For more information, see the following resources:

• Create web APIs with ASP.NET Core
• Tutorial: Create a minimal API with ASP.NET Core
• ASP.NET Core web API documentation with Swagger / OpenAPI
• Razor Pages with Entity Framework Core in ASP.NET Core - Tutorial 1 of 8
• Routing to controller actions in ASP.NET Core
• Controller action return types in ASP.NET Core web API
• Deploy ASP.NET Core apps to Azure App Service
• Host and deploy ASP.NET Core
• Create a web API with ASP.NET Core

This tutorial teaches the basics of building a controller-based web API that uses a database. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help in choosing between minimal APIs and controller-based APIs, see APIs overview. For a tutorial on creating a minimal API, see Tutorial: Create a minimal API with ASP.NET Core.

In this tutorial, you learn how to:

At the end, you have a web API that can manage "to-do" items stored in a database.

This tutorial creates the following API:

The following diagram shows the design of the app.

dotnet add package Microsoft.EntityFrameworkCore.InMemory

The project template creates a WeatherForecast API. Call the Get method from a browser to test the app.

JSON similar to the following is returned:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

A model is a set of classes that represent the data that the app manages. The model for this app is a single TodoItem class.

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

The database context is the main class that coordinates Entity Framework functionality for a data model. This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

• Enter the following code:

  C# Copy

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models
  {
      public class TodoContext : DbContext
      {
          public TodoContext(DbContextOptions<TodoContext> options)
              : base(options)
          {
          }
  
          public DbSet<TodoItem> TodoItems { get; set; }
      }
  }
  

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. The container provides the service to controllers.

Update Startup.cs with the following highlighted code:

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
               opt.UseInMemoryDatabase("TodoList"));
            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

The preceding code:

• Removes unused using declarations.
• Adds the database context to the DI container.
• Specifies that the database context will use an in-memory database.

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet tool install --global dotnet-aspnet-codegenerator
dotnet tool update -g Dotnet-aspnet-codegenerator
dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

The generated code:

• Marks the class with the [ApiController] attribute. This attribute indicates that the controller responds to web API requests. For information about specific behaviors that the attribute enables, see Create web APIs with ASP.NET Core.
• Uses DI to inject the database context (TodoContext) into the controller. The database context is used in each of the CRUD methods in the controller.

The ASP.NET Core templates for:

• Controllers with views include [action] in the route template.
• API controllers don't include [action] in the route template.

When the [action] token isn't in the route template, the action name is excluded from the route. That is, the action's associated method name isn't used in the matching route.

Replace the return statement in the PostTodoItem to use the nameof operator:

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the value of the to-do item from the body of the HTTP request.

For more information, see Attribute routing with Http[Verb] attributes.

The CreatedAtAction method:

• Returns an HTTP 201 status code if successful. HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. For more information, see 201 Created.
• References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

This tutorial uses Postman to test the web API.

• Install Postman
• Start the web app.
• Start Postman.
• Disable SSL certificate verification:
  • Postman for Windows: Postman for Windows File > Settings (General tab), disable SSL certificate verification.
  • Postman for macOS: Postman for Windows Postman > Settings (General tab), disable SSL certificate verification.

    Warning

    Re-enable SSL certificate verification after testing the controller.

• Create a new request.

• Set the HTTP method to POST.

• Set the URI to https://localhost:<port>/api/todoitems. For example, https://localhost:5001/api/todoitems.

• Select the Body tab.

• Select the raw radio button.

• Set the type to JSON (application/json).

• In the request body enter JSON for a to-do item:

  JSON Copy

  {
    "name":"walk dog",
    "isComplete":true
  }
  

• Select Send.

  

• Select the Headers tab in the Response pane.

• Copy the Location header value:

  

• Set the HTTP method to GET.

• Set the URI to https://localhost:<port>/api/todoitems/1. For example, https://localhost:5001/api/todoitems/1.

• Select Send.

These methods implement two GET endpoints:

• GET /api/todoitems
• GET /api/todoitems/{id}

Test the app by calling the two endpoints from a browser or Postman. For example:

• https://localhost:5001/api/todoitems
• https://localhost:5001/api/todoitems/1

A response similar to the following is produced by the call to GetTodoItems:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

• Create a new request.
• Set the HTTP method to GET.
• Set the request URI to https://localhost:<port>/api/todoitems. For example, https://localhost:5001/api/todoitems.
• Set Two pane view in Postman.
• Select Send.

This app uses an in-memory database. If the app is stopped and started, the preceding GET request will not return any data. If no data is returned, POST data to the app.

The [HttpGet] attribute denotes a method that responds to an HTTP GET request. The URL path for each method is constructed as follows:

• Start with the template string in the controller's Route attribute:

  C# Copy

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  {
      private readonly TodoContext _context;
  
      public TodoItemsController(TodoContext context)
      {
          _context = context;
      }
  

• Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. This sample doesn't use a template. For more information, see Attribute routing with Http[Verb] attributes.

In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. 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, assuming there are no unhandled exceptions. Unhandled exceptions are translated into 5xx errors.

ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can return two different status values:

• If no item matches the requested ID, the method returns a 404 NotFound error code.
• Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200 response.

Examine the PutTodoItem method:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. The response is 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.

If you get an error calling PutTodoItem, call GET to ensure there's an item in the database.

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":

  {
    "id":1,
    "name":"feed fish",
    "isComplete":true
  }

The following image shows the Postman update:

Examine the DeleteTodoItem method:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<ActionResult<TodoItem>> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return todoItem;
}

Use Postman to delete a to-do item:

• Set the method to DELETE.
• Set the URI of the object to delete (for example https://localhost:5001/api/todoitems/1).
• Select Send.

Currently the sample app exposes the entire TodoItem object. Production apps typically limit the data that's input and returned using a subset of the model. 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 may be used to:

• Prevent over-posting.
• Hide properties that clients are not supposed to view.
• Omit some properties in order to reduce payload size.
• Flatten object graphs that contain nested objects. Flattened object graphs can be more convenient for clients.

To demonstrate the DTO approach, update the TodoItem class to include a secret field:

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
    public string Secret { get; set; }
}

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 DTO model:

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Update the TodoItemsController to use TodoItemDTO:

    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
    {
        if (id != todoItemDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoItemDTO.Name;
        todoItem.IsComplete = todoItemDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }

    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoItemDTO.IsComplete,
            Name = todoItemDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id) =>
         _context.TodoItems.Any(e => e.Id == id);

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
        new TodoItemDTO
        {
            Id = todoItem.Id,
            Name = todoItem.Name,
            IsComplete = todoItem.IsComplete
        };       
}