Erstellen einer RESTful-Web-API-Vorlage in .NET Core 1.1

Erstellen einer RESTful-Web-API-Vorlage in .NET Core 1.1 – Teil 1:Zurückgeben von HTTP-Codes

Ich habe bereits RESTful-APIs mit dem .NET-Framework und der WebAPI erstellt, aber noch nichts Kommerzielles mit .NET Core. .NET Core ist seit einiger Zeit draußen – Version 1.1 wurde bei Connect(); veröffentlicht; //2016 – Ich habe gehört, dass einige Kunden jetzt bereit sind, damit zu experimentieren, um einige der potenziellen Leistungs- und Stabilitätsgewinne zu erzielen.

Um mich auf neue Kundenanfragen vorzubereiten, habe ich damit experimentiert, eine einfache RESTful-API mit .NET Core zu erstellen, um zu sehen, wie sie sich von der alternativen Version mit dem regulären .NET Framework unterscheidet … und ich habe festgestellt, dass sie wirklich ziemlich anders ist.

Ich habe bereits über einige der Herausforderungen beim Upgrade von .NET Core 1.0 auf 1.1 beim Erstellen eines neuen Projekts geschrieben – in diesem Beitrag geht es darum, wie man mit der Standardvorlage für Web-API-Projekte beginnt und sie in etwas Ähnlicheres umwandelt ein nützliches Projekt zum Hosten von RESTful-Microservices.

In diesem ersten Beitrag der Serie geht es darum, das Standardprojekt in einen guten HTTP-Bürger zu verwandeln und HTTP-Statuscodes zurückzugeben.

Wenn ich ein neues WebAPI-Projekt mit .NET Core 1.1 aus der Visual Studio-Standardvorlage erstelle, werden eine Reihe von Dateien im Projekt erstellt. Der interessantere ist der „ValuesController“ – dieser enthält die Standardverben, die mit RESTful-Diensten verbunden sind, GET, POST, PUT und DELETE. Ich habe den unten erstellten Standardcode eingefügt:

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)
        {
        }
    }
}

Eines der Dinge, die ich daran nicht mag und die sehr einfach zu ändern wären, ist der Rückgabetyp jedes Verbs. Ein guter RESTful-Dienst sollte HTTP-Statuscodes zurückgeben, die das Ergebnis der Aktion beschreiben – in der Regel 200 Erfolgscodes:

200 – Anfrage ist in Ordnung;
201 – Ressource erfolgreich erstellt;
202 – Aktualisierung akzeptiert und wird verarbeitet (kann jedoch abgelehnt werden);
204 – Anfrage verarbeitet und es gibt keinen zurückzugebenden Inhalt.

Außerdem enthalten Antworten auf RESTful-Aktionen manchmal folgende Informationen:

200 – OK – Wenn die Aktion GET ist, enthält die Antwort ein Objekt (oder eine Liste von Objekten), die angefordert wurden.
201 – Erstellt – Die Antwort enthält das Objekt, das erstellt wurde, sowie den eindeutigen URI, der zum Abrufen dieses Objekts erforderlich ist.
202 – Akzeptiert – Die Antwort enthält das Objekt, für das eine Aktualisierung angefordert wurde.
204 – Kein Inhalt zurückgeben – dies könnte als Ergebnis einer Löschanforderung zurückgegeben werden, wo es keinen Sinn machen würde, ein Objekt zurückzugeben (da es theoretisch nicht mehr existiert).

Ich denke, der Standard-ValuesController wäre nützlicher, wenn er ein Muster für die Rückgabe von Antworten mit korrekt konfigurierten HTTP-Statuscodes implementieren würde, und ich denke, der erste Schritt dazu wäre, den unten stehenden Standardcode für den ValueController zu verwenden (der – als Standardvorlage – macht offensichtlich noch nichts Sinnvolles).

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();
        }
    }
}

Die wichtigsten Änderungen, die ich bisher vorgenommen habe, sind:

Der Rückgabetyp jeder Aktion ist jetzt IActionResult, wodurch HTTP-Statuscodes zurückgegeben werden können.
Für die GET-Aktionen habe ich nur die zurückgegebenen Objekte (die einfache Zeichenfolgen sind) mit dem Ok-Ergebnis umschlossen.
Für die POST-Aktion habe ich das Ergebnisobjekt Erstellt verwendet. Dies unterscheidet sich von OK, da es zusätzlich zum Einschließen eines Objekts auch einen URI enthält, der auf den Speicherort des Objekts verweist.
Für die PUT-Aktion habe ich einfach das zurückgegebene Objekt mit dem Accepted-Ergebnis umschlossen. Der Rückgabetyp Accepted ist neu in .NET Core v1.1 – dieser wird nicht kompiliert, wenn Sie auf frühere Versionen abzielen.
Schließlich habe ich für die DELETE-Aktion, anstatt void zurückzugeben, einen NoContent-Ergebnistyp zurückgegeben.

Ich mag es wirklich, wie .NET Core v1.1 bei der Erstellung großartiger RESTful-Dienste auf saubere und einfache Weise backt, und bevorzuge es der zuvor in .NET verwendeten Methode. Ich plane eine Reihe weiterer Posts, die sich auf einige funktionale und nicht funktionale Aspekte der Erstellung eines sauberen RESTful-Dienstes konzentrieren:

So testen Sie diesen Dienst mit einem ReST-Client;
So stellen Sie diesen Dienst in einem Docker-Container bereit;
Verbesserung der Suche des Dienstes;
Wie Sie die Leistung Ihres Dienstes verbessern können;
So sichern Sie die Header der Antwort;
Dokumentation dieses Kurses mit Swagger und Swashbuckle;
Zugriff auf diesen Webdienst von JQuery.

Über mich: Ich poste regelmäßig über .NET – wenn Sie interessiert sind, folgen Sie mir bitte auf Twitter oder sehen Sie sich hier meine früheren Beiträge an. Danke!