Ho già creato API RESTful con .NET Framework e WebAPI, ma ancora niente di commerciale con .NET Core. .NET Core è uscito da un po' di tempo:la versione 1.1 è stata rilasciata su Connect(); //2016 – Ho sentito che alcuni clienti ora sono disposti a sperimentare questo per ottenere alcuni dei potenziali miglioramenti in termini di prestazioni e stabilità.
Per prepararmi alle nuove richieste dei clienti, ho sperimentato la creazione di una semplice API RESTful con .NET Core per vedere quanto è diversa dalla versione alternativa con il normale .NET Framework... e ho scoperto che è davvero molto diversa.
Ho già scritto di alcune delle sfide nell'aggiornamento da .NET Core 1.0 a 1.1 durante la creazione di un nuovo progetto:questo post spiega come iniziare con il modello predefinito per i progetti API Web e trasformarlo in qualcosa che è più simile un progetto utile per ospitare microservizi RESTful.
Questo primo post della serie riguarda la trasformazione del progetto predefinito in un buon cittadino HTTP e la restituzione dei codici di stato HTTP.
Quando creo un nuovo progetto WebAPI utilizzando .NET Core 1.1 dal modello predefinito di Visual Studio, nel progetto vengono creati numerosi file. Il più interessante è il "ValuesController":contiene i verbi standard associati ai servizi RESTful, GET, POST, PUT e DELETE. Ho incollato il codice predefinito creato di seguito:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
namespace MyWebAPI.Controllers
{
[Route("api/[controller]")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
// GET api/values/5
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
// POST api/values
[HttpPost]
public void Post([FromBody]string value)
{
}
// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, [FromBody]string value)
{
}
// DELETE api/values/5
[HttpDelete("{id}")]
public void Delete(int id)
{
}
}
}
Tuttavia, una delle cose che non mi piace di questo che sarebbe molto facile cambiare è il tipo di ritorno di ogni verbo. Un buon servizio RESTful dovrebbe restituire codici di stato HTTP che descrivono il risultato dell'azione, in genere 200 codici per il successo:
- 200 – La richiesta è ok;
- 201 – Risorsa creata con successo;
- 202 – Aggiornamento accettato e verrà elaborato (sebbene possa essere rifiutato);
- 204 – Richiesta elaborata e nessun contenuto da restituire.
Inoltre, le risposte alle azioni RESTful a volte conterranno informazioni:
- 200 – OK – se l'azione è GET, la risposta conterrà un oggetto (o un elenco di oggetti) che sono stati richiesti.
- 201 – Creato – la risposta conterrà l'oggetto che è stato creato e anche l'URI univoco richiesto per ottenere quell'oggetto.
- 202 – Accettato – la risposta conterrà l'oggetto per il quale è stato richiesto un aggiornamento.
- 204 – Nessun contenuto restituire – questo potrebbe essere restituito a seguito di una richiesta di eliminazione, dove non avrebbe senso restituire un oggetto (poiché teoricamente non esiste più).
Penso che ValuesController predefinito sarebbe più utile se implementasse un modello di restituzione di risposte con codici di stato HTTP correttamente configurati e penso che il primo passo verso questo sarebbe utilizzare il codice predefinito di seguito per ValueController (che, come modello predefinito – ovviamente non fa ancora nulla di utile).
using Microsoft.AspNetCore.Mvc;
namespace MyWebAPI.Controllers
{
[Route("api/[controller]")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IActionResult Get()
{
return Ok(new string[] { "value1", "value2" });
}
// GET api/values/5
[HttpGet("{id}")]
public IActionResult Get(int id)
{
return Ok("value");
}
// POST api/values
[HttpPost]
public IActionResult Post([FromBody]string value)
{
return Created($"api/Values/{value}", value);
}
// PUT api/values/5
[HttpPut("{id}")]
public IActionResult Put(int id, [FromBody]string value)
{
return Accepted(value);
}
// DELETE api/values/5
[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
return NoContent();
}
}
} Le principali modifiche che ho apportato finora sono:
- Il tipo di restituzione di ciascuna azione è ora IActionResult, che consente la restituzione dei codici di stato HTTP.
- Per le azioni GET, ho appena eseguito il wrapping degli oggetti restituiti (che sono semplici stringhe) con il risultato Ok.
- Per l'azione POST, ho utilizzato l'oggetto risultato Creato. È diverso da OK perché oltre a includere un oggetto, include anche un URI che punta alla posizione dell'oggetto.
- Per l'azione PUT, ho appena eseguito il wrapping dell'oggetto restituito con il risultato Accepted. Il tipo restituito di Accepted è nuovo in .NET Core v1.1:questo non verrà compilato se stai prendendo di mira le versioni precedenti.
- Infine, per l'azione DELETE, invece di restituire void ho restituito un tipo di risultato NoContent.
Mi piace molto il modo in cui .NET Core v1.1 crea ottimi servizi RESTful in modo pulito e semplice e lo preferisco al modo precedentemente utilizzato in .NET. Sto pianificando una serie di altri post che si concentreranno su alcuni aspetti funzionali e non funzionali della creazione di un servizio RESTful pulito:
- Come testare questo servizio utilizzando un client ReST;
- Come distribuire questo servizio in un container Docker;
- Come migliorare la modalità di ricerca del servizio;
- Come migliorare le prestazioni del tuo servizio;
- Come proteggere le intestazioni della risposta;
- Come documentare questo corso utilizzando Swagger e Swashbuckle;
- Come accedere a questo servizio web da JQuery.
Su di me: Posto regolarmente su .NET:se sei interessato, seguimi su Twitter o dai un'occhiata ai miei post precedenti qui. Grazie!