Best practices voor RESTful-web-API-implementatie

In dit artikel worden aanbevolen procedures beschreven voor het implementeren, uitrollen en beheren van een RESTful-web-API. Het richt zich op het verwerken van verzoeken, prestaties, betrouwbaarheid, publicatie en bewaking. Zie Web API design voor richtlijnen over het modelleren van resources en API-ontwerp.

De architectuurrichtlijnen zijn van toepassing op implementatietalen en frameworks. De C#-voorbeelden illustreren ASP.NET Core controllers.

Het verwerken van aanvragen

Houd rekening met de volgende punten wanneer u de code voor het verwerken van aanvragen implementeert.

Semantiek van HTTP-methode behouden en idempotentie implementeren

Gebruik GET om resourcegegevens te retourneren en HEAD om antwoordheaders zonder hoofdtekst te retourneren. Gebruik geen van beide methoden om resources te maken, bij te werken of te verwijderen.

GET, HEAD, PUT en DELETE moeten idempotent zijn, dus het herhalen van een identiek verzoek heeft hetzelfde beoogde effect als het één keer uit te voeren. Delete wijzigt bijvoorbeeld de resourcestatus, maar als u deze herhaalt, worden er geen extra resources verwijderd. De eerste DELETE-aanvraag retourneert mogelijk 204 (geen inhoud), terwijl een volgende aanvraag 404 (niet gevonden) retourneert.

POST en PATCH zijn niet inherent idempotent. Een PATCH-bewerking waarmee een eigenschap wordt ingesteld op een waarde kan idempotent zijn, maar een bewerking die een teller incrementeert, is dat niet. Documenteer welke status wijzigende bewerkingen clients veilig opnieuw kunnen proberen. Als u nieuwe pogingen ondersteunt voor bewerkingen die niet van nature idempotent zijn, implementeer en documenteer hoe de service dubbele effecten voorkomt. Voor de methodesemantiek, zie HTTP-requestmethoden.

Aanvraaggegevens valideren en toegang tot velden beheren

Definieer request- en responsemodellen die alleen de velden in het API-contract beschikbaar maken. Koppel deze modellen aan de opgeslagen gegevens in plaats van verzoekinhouden rechtstreeks aan database-entiteiten te binden of elke opgeslagen eigenschap te retourneren. Voorkom dat aanroepers beveiligde eigenschappen wijzigen door extra velden in te dienen, en laat eigenschappen weg die ze niet mogen lezen. DTO's (Data Transfer Objects) zijn één manier om deze grens af te dwingen. Zie Overposting voorkomen in ASP.NET Core voor meer informatie.

Valideer vereiste velden, typen, waardenbereiken en bedrijfsregels voordat u wijzigingen opslaat. Als u veldselectie ondersteunt, valideert u aangevraagde velden op basis van een toegestane lijst en de machtigingen van de beller voordat u de respons samenstelt. Pas ook gedocumenteerde limieten toe op filteren en sorteren. Zie Paginering en filteren implementeren voor de bijbehorende contractkeuzen.

Beperk neveneffecten van POST-acties die resources aanmaken

Wanneer een POST-aanvraag een resource maakt, beperkt u de effecten ervan tot die resource en rechtstreeks gerelateerde resources. Het maken van een order kan bijvoorbeeld ook inventaris bijwerken en factureringsgegevens genereren. Er mag geen niet-gerelateerde informatie worden gewijzigd.

Vermijd het implementeren van veeleisende POST-, PUT- en DELETE-bewerkingen

Vermijd het ontwerpen van uw API op basis van chatty-bewerkingen . Elke aanvraag gaat gepaard met protocol-, netwerk- en rekenoverhead. Als u bijvoorbeeld 100 kleinere aanvragen uitvoert in plaats van één grotere batchaanvraag, treedt er extra overhead op in de client, in het netwerk en op de resourceserver. Voor workloads die bulkbewerkingen nodig hebben, kunt u begrensde batchaanvragen overwegen in plaats van veel afzonderlijke aanvragen.

• Een GET-aanvraag voor een verzameling kan meerdere resources tegelijk ophalen.
• Een POST-aanvraag kan de details voor meerdere nieuwe resources bevatten en ze allemaal toevoegen aan dezelfde verzameling.
• Een PUT-aanvraag kan de volledige set resources in een verzameling vervangen.
• Een DELETE-aanvraag kan een volledige verzameling verwijderen.

Definieer maximale batchgrootten, payloadgroottes, uitvoeringstijden en concurrentie. Geef op of een batch atomisch is of gedeeltelijk kan slagen en retourneer een resultaat voor elke bewerking. Elke bewerking in de batch autoriseren en valideren.

Als u OData gebruikt, kunt u ASP.NET Core OData gebruiken om batchaanvragen te implementeren. Zie ASP.NET Core OData-overzicht voor meer informatie.

Volg de HTTP-specificatie bij het verzenden van een reactie

Retourneer de juiste HTTP-statuscode, headers en hoofdtekstindeling, zodat clients het antwoord kunnen interpreteren en afhandelen.

Een POST-bewerking die synchroon een resource creëert, moet bijvoorbeeld 201 (gemaakt) retourneren en de resource in de Location antwoordheader identificeren. Een bewerking die werk accepteert voor latere verwerking kan 202 (Geaccepteerd) retourneren, maar dat antwoord geeft niet aan dat de verwerking is geslaagd. Neem geen antwoordtekst op met 204 (geen inhoud) of 304 (niet gewijzigd). Zie HTTP-requestmethoden voor meer informatie.

Ondersteuning voor inhoudsonderhandeling

Een responsbody kan gegevens bevatten in verschillende indelingen, zoals JSON of XML. Clients kunnen de Accept aanvraagheader gebruiken om ondersteunde mediatypen op te geven. Een client die een afbeelding aanvraagt, kan bijvoorbeeld opgeven image/jpeg, image/gif, image/png. Retourneer een ondersteunde weergave en identificeer het mediatype in de Content-Type antwoordheader.

Als de client geen header opgeeft Accept , gebruikt u een gedocumenteerde standaardindeling. ASP.NET Core controllers maken standaard gebruik van JSON-formatters. Definieer wat er gebeurt wanneer de API geen aangevraagde weergave kan produceren. Configureer bijvoorbeeld de API om 406 (niet acceptabel) te retourneren in plaats van op de achtergrond een niet-ondersteunde indeling te retourneren. Zie Antwoordgegevens opmaken in ASP.NET Core Web-API voor meer informatie.

Voor verzoeken met een hoofdtekst controleert u de Content-Type van het verzoek en accepteert u alleen de indelingen die door de operatie worden ondersteund. Retourneert 415 (niet-ondersteund mediatype) voor een niet-ondersteunde indeling. Deze controle staat los van responsonderhandeling via Accept. Configureer in ASP.NET Core invoerindelingen en gebruik [Consumes] wanneer u de aanvraagindelingen van een bewerking wilt beperken. Zie Web-API's maken met ASP.NET Core voor meer informatie.

De geselecteerde STRATEGIE voor API-versiebeheer implementeren

Pas de versiebeheerstrategie die u tijdens het ontwerp hebt gekozen consistent toe in de applicatie en gateway. Leid verzoeken door naar de handler en het antwoordschema voor de geselecteerde versie. Definieer het gedrag voor weggelaten, ongeldige en niet-ondersteunde versie-id's in plaats van stilzwijgend te wijzigen welk contract een bestaande aanroeper ontvangt.

Behoud de request- en responsecontracten van ondersteunde versies. Wanneer u een incompatibele wijziging introduceert, moet u een nieuwe versie opgeven en ondersteunde eerdere versies beschikbaar houden. Afhandelen van aanvragen van oudere aanroepen die nieuw toegevoegde optionele velden weglaten. Zie API-versiebeheer en -compatibiliteit voor meer informatie.

Houd gegenereerde resourcekoppelingen en weergaven in de cache consistent met de geselecteerde versie. Voor versiebeheer op basis van headers moet u ervoor zorgen dat aanvragen voor verschillende versies in de cache worden onderscheiden in plaats van alleen op de URI te vertrouwen.

Tenantcontext oplossen en autoriseren

Voor een multitenant-API bepaal de tenant voor elke aanvraag en controleer of de geverifieerde aanroeper toegang heeft tot die tenant. Behandel tenant-id's in paden, hostnamen en headers alleen als routeringsinvoer. Zie Toewijzingsaanvragen aan tenants in een multitenant-oplossing voor meer informatie.

Gebruik de context van de geautoriseerde tenant consistent bij het opvragen of bijwerken van gegevens en bij het overdragen van werk aan achtergrondprocessors. Als toepassings- of gatewaycaches tenantspecifieke gegevens opslaan, neemt u de tenant-id op in de cachesleutel. Zie API Management-functies die ondersteuning bieden voor multitenancy voor specifieke richtlijnen voor gateways.

Geef koppelingen die HATEOAS-stijl navigatie en ontdekking van resources ondersteunen.

Hypertext als de Engine of Application State (HATEOAS) gebruikt koppelingen om clients te helpen bronnen te ontdekken en erdoor te navigeren. Een antwoord met klantgegevens kan bijvoorbeeld koppelingen naar de orders van die klant bevatten. Beschrijf de bewerkingen die elke gekoppelde resource ondersteunt, zoals GET, POST, PUT en DELETE, en geef de bijbehorende URI's op. Zie API-ontwerp voor meer informatie.

In het volgende voorbeeld wordt een toepassingsgedefinieerde koppelingsweergave gebruikt. Documenteer de conventies in plaats van ervan uit te gaan dat clients aangepaste koppelingsvelden kunnen interpreteren. Een GET-aanvraag voor een klant retourneert koppelingen naar de orders van die klant:

GET https://api.contoso.com/customers/2 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"customerId": 2,"customerName": "Bert","links": [
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "PUT",
     "types": ["application/x-www-form-urlencoded"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "DELETE",
     "types": []},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "POST",
     "types": ["application/x-www-form-urlencoded"]}
]}

De volgende Customer record vertegenwoordigt de klantgegevens. De Links eigenschap bevat de HATEOAS-koppelingen.

public sealed record Customer(
    int CustomerId,
    string CustomerName,
    IReadOnlyList<Link> Links);

public sealed record Link(
    string Rel,
    string Href,
    string Action,
    IReadOnlyList<string> Types);

De GET-bewerking haalt de klantgegevens op uit de opslag, bouwt een Customer record samen met de bijbehorende koppelingen en retourneert een JSON-antwoord. Elke koppeling bevat de volgende velden:

• De relatie (Rel) tussen de geretourneerde resource en de gekoppelde resource. In dit voorbeeld verwijst self naar de klant en verwijst orders naar de orderverzameling van de klant.
• De hyperlink (Href) voor het object dat wordt beschreven door de koppeling, in de vorm van een URI.
• Het type HTTP-aanvraag (Action) dat naar de URI kan worden verzonden.
• De indeling van gegevens (Types) die moet worden opgegeven in de HTTP-aanvraag of die in het antwoord kan worden geretourneerd, afhankelijk van het type van de aanvraag.

De in het voorbeeld-HTTP-antwoord weergegeven HATEOAS-links geven aan dat een clienttoepassing de volgende bewerkingen kan uitvoeren:

• Een HTTP GET-aanvraag naar https://api.contoso.com/customers/2 om de klantgegevens op te halen als XML of JSON.
• Een HTTP PUT-aanvraag naar https://api.contoso.com/customers/2 om de klantgegevens te wijzigen. De requestbody van de aanvraag maakt gebruik van deze indeling: application/x-www-form-urlencoded.
• Een HTTP DELETE-aanvraag naar https://api.contoso.com/customers/2 om de klantrecord te verwijderen. Deze bewerking vereist geen request body en retourneert geen response body.
• Een HTTP GET-aanvraag om https://api.contoso.com/customers/2/orders de orders van de klant op te halen als XML of JSON.
• Een HTTP POST-aanvraag naar https://api.contoso.com/customers/2/orders om een bestelling voor de klant aan te maken. De aanvraagbody maakt gebruik van deze indeling: application/x-www-form-urlencoded.

Afhandeling van uitzonderingen

Als een bewerking een uitzondering genereert die niet wordt verwerkt, kunt u de volgende richtlijnen overwegen.

Vastleggen van uitzonderingen en relevante antwoorden aan clients geven

Handel uitzonderingen consistent af en retourneer een zinvolle foutreactie die veilig is om te delen met clients. Retourneer geen uitzonderingsobjecten, stacktraceringen of interne implementatiedetails in productiereacties. Retourneer een HTTP-statuscode die de fout weerspiegelt in plaats van statuscode 500 te retourneren voor elke situatie. Als een gebruikersaanvraag bijvoorbeeld een database-update veroorzaakt die een beperking schendt (zoals het verwijderen van een klant met openstaande orders), retourneert u 409 (Conflict) en een niet-gevoelige uitleg. Retourneer 400 (ongeldige aanvraag) voor ongeldige invoer- of aanvraagvalidatiefouten, niet voor onverwachte serverfouten. Zie Statuscodes voor HTTP-statusdefinities. Raadpleeg Fouten afhandelen in ASP.NET Core voor implementatierichtlijnen.

De volgende controller wijst verwachte domeinresultaten toe aan HTTP-antwoorden. De repositorybewerking controleert autorisatie en openstaande orders als onderdeel van de verwijderingsbewerking. Onverwachte fouten worden doorgegeven aan gecentraliseerde uitzonderingsafhandeling in plaats van stil te worden opgevangen bij elke actie.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("customers")]
public sealed class CustomersController(ICustomerRepository repository) : ControllerBase
{
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> DeleteCustomer(int id, CancellationToken cancellationToken)
    {
        var outcome = await repository.DeleteAuthorizedAsync(id, User, cancellationToken);

        return outcome switch
        {
            DeleteOutcome.Deleted => NoContent(),
            DeleteOutcome.NotFound => NotFound(),
            DeleteOutcome.HasOutstandingOrders => Conflict(new ProblemDetails
            {
                Status = StatusCodes.Status409Conflict,
                Title = "The customer has outstanding orders."
            }),
            _ => throw new InvalidOperationException("Unknown deletion outcome.")
        };
    }
}

public enum DeleteOutcome
{
    Deleted,
    NotFound,
    HasOutstandingOrders
}

De hostinglaag kan aanvragen weigeren voordat ze de API bereiken. Authenticatiefouten kunnen bijvoorbeeld leiden tot 401-responses (Niet geautoriseerd). Controleer na authenticatie of de aanroeper is gemachtigd voor toegang tot de aangevraagde resource. Geef 403 (Verboden) terug wanneer autorisatie mislukt.

Wees consistent met het verwerken van uitzonderingen en registreer informatie over fouten

Als u uitzonderingen consistent wilt afhandelen, kunt u overwegen om een globale strategie voor foutafhandeling in de hele web-API te implementeren. Diagnostische gegevens op de server registreren, maar geheimen, toegangstokens en gevoelige persoonlijke gegevens uitsluiten. Gevoelige waarden afschermen voordat logboekvermeldingen worden geschreven en de toegang tot logboeken beperken tot geautoriseerde gebruikers. Zie Architectuurstrategieën voor bewaking en detectie van bedreigingen voor meer informatie.

Gebruik in ASP.NET Core middleware voor uitzonderingsafhandeling en Problem Details-responses voor een consistent foutcontract. Configureer productieantwoorden om diagnostische gegevens weg te laten en voeg een correlatie-id toe die ondersteuningsteams kunnen gebruiken om de bijbehorende logboeken te vinden. Zie Fouten afhandelen in ASP.NET Corevoor meer informatie.

Onderscheid maken tussen fouten van client-zijde en serverzijde

Gebruik HTTP 4xx-statuscodes voor clientfouten en HTTP 5xx-statuscodes voor serverfouten. Bewaar dit onderscheid in foutreacties.

Toegang tot gegevens van clientzijde optimaliseren

Frequente aanvragen en grote antwoorden kunnen het netwerk tot een knelpunt maken. Verminder onnodige overdrachten wanneer u het ophalen en bijwerken van resources implementeert.

Ondersteuning voor caching aan clientzijde

Gebruik de Cache-Control antwoordheader om op te geven of clients en tussenliggende servers een antwoord kunnen opslaan en hoelang deze vers blijft.

In het volgende voorbeeld ziet u een HTTP GET-aanvraag en de desbetreffende reactie die een Cache-Control-header bevat:

GET https://api.contoso.com/orders/2 HTTP/1.1

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

In dit voorbeeld blijft het antwoord 600 seconden actueel. De private directive staat opslag toe in een privécache, zoals een browsercache, maar verbiedt opslag in een gedeelde cache. Gebruik public alleen voor antwoorden die veilig zijn om te delen tussen bellers. Gebruik no-store voor gevoelige antwoorden die niet mogen worden opgeslagen.

Stel in een ASP.NET Core controller cacheheaders in voordat u het antwoord retourneert:

Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue
{
    Private = true,
    MaxAge = TimeSpan.FromMinutes(10)
};

De API bepaalt het cachebeleid en de validators in de antwoorden. Clients en tussenliggende servers gebruiken die informatie om hun caches te beheren. Stel deze headers consistent in, zodat aanroepers antwoorden kunnen hergebruiken zonder onnodige gegevensoverdracht.

Om te bepalen max-age, moet u overwegen hoeveel veroudering de workload kan tolereren. Een resource kan veranderen terwijl een response in de cache nog steeds vers is. Wanneer de versheid verloopt, kan een cache de response opnieuw valideren in plaats van deze te verwijderen en de hele representatie opnieuw te downloaden. Gebruik geen lange versheidsduur voor gegevens waarvan wijzigingen direct zichtbaar moeten zijn.

Lever ETags om queryverwerking te optimaliseren

Een entiteitstag (ETag) is een ondoorzichtige validator voor een geselecteerde resourceweergave. Clients kunnen het samen met een gecachte respons bewaren en deze in If-None-Match verzenden om te controleren of de weergave is gewijzigd. Een overeenkomende GET- of HEAD-aanvraag retourneert 304 (niet gewijzigd) zonder antwoordtekst.

Genereer een validator die consistent blijft in verschillende toepassingsinstanties en verandert wanneer de weergave verandert.

De volgende controller hashes de exacte JSON-bytes die het retourneert en hergebruikt de geconfigureerde JSON-opties van de toepassing. FileContentResult past ASP.NET Core-verwerking van voorwaardelijke reacties toe zonder aangepaste resultaatwikkelaars. De repository retourneert alleen een order die de aanroeper mag lezen. Configureer verificatie en autorisatie in de host-applicatie.

using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrdersController(IOrderRepository repository,IOptions<JsonOptions> jsonOptions) : ControllerBase
{
    [HttpGet("{id:int}")]
    [HttpHead("{id:int}")]
    public async Task<IActionResult> GetOrder(int id, CancellationToken cancellationToken)
    {
        var order = await repository.FindAuthorizedAsync(id, User, cancellationToken);
        if (order is null)
        {
            return NotFound();
        }

        var payload = JsonSerializer.SerializeToUtf8Bytes(order, jsonOptions.Value.JsonSerializerOptions);
        var etag = new EntityTagHeaderValue($"\"{Convert.ToHexString(SHA256.HashData(payload))}\"");

        Response.GetTypedHeaders().CacheControl = new CacheControlHeaderValue
        {
            Private = true,
            MaxAge = TimeSpan.FromMinutes(10)
        };

        return new FileContentResult(payload, "application/json")
        {
            EntityTag = etag
        };
    }
}

In dit voorbeeld wordt de weergave gebufferd en wordt de bestelling zelfs voor een voorwaardelijk verzoek gelezen. Gebruik deze alleen voor afgebakende, niet-gevoelige antwoorden. Voor grote resources kunt u overwegen een opgeslagen versietoken te gebruiken dat wordt gewijzigd wanneer de geselecteerde weergave verandert, zodat u een aanvraag kunt valideren zonder de volledige payload te genereren. Als inhoudsonderhandeling, compressie of gatewaytransformaties de weergave wijzigen, moet u ervoor zorgen dat validators en cachevariaties juist blijven voor die weergave.

Een antwoord bevat het ETag- en cachebeleid. In de volgende voorbeelden ziet u de eerste 16 hexadecimale tekens (64 bits) van de SHA-256-hash van de weergegeven JSON-body, gevolgd door ... voor de beknoptheid. Werkelijke headers bevatten de volledige hash zonder het beletselteken.

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
ETag: "3097D1FD51082205..."
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

Ondersteun voorwaardelijke GET-aanvragen, zodat aanroepers responses in de cache opnieuw kunnen valideren zonder een ongewijzigde weergave te downloaden. Implementeer het volgende aanvraag- en antwoordgedrag:

1. Accepteer voorwaardelijke GET-aanvragen die een ETag in de If-None-Match-header meesturen, zoals:

   GET https://api.contoso.com/orders/2 HTTP/1.1
   If-None-Match: "3097D1FD51082205..."
   

2. Vergelijk de huidige ETag voor de aangevraagde resource (order 2 in dit voorbeeld) met de If-None-Match voorwaarde.

   • Als de voorwaarde overeenkomt, retourneert u 304 (niet gewijzigd) zonder antwoordtekst.

   • Als niet aan de voorwaarde is voldaan, retourneert u 200 (OK) met de huidige weergave.

   • Als de aangevraagde resource niet meer bestaat, retourneer 404 (niet gevonden).

Gebruik waar mogelijk frameworkondersteuning voor voorwaardelijke verzoeken. Als u zelf vergelijkingen implementeert, moet u alle opgegeven entiteitstags, jokertekenvoorwaarden en zwakke versus sterke vergelijkingsregels afhandelen in plaats van alleen de eerste tag te vergelijken. Neem de juiste ETag- en cacheheaders op in 304 -antwoorden (niet gewijzigd) en voer autorisatie uit voordat resourcemetagegevens worden geretourneerd.

ETags gebruiken ter ondersteuning van optimistische gelijktijdige toegang

Als u wilt voorkomen dat er updates verloren gaan, evalueert u If-Match de voorwaarden voor statuswijzigende verzoeken op basis van de huidige ETag van de resource. Hierdoor kan de API een wijziging weigeren op basis van een weergave die al door een andere bewerking is gewijzigd. Implementeer het volgende gedrag:

1. Accepteer updateaanvragen die de verwachte versie in de If-Match header identificeren. De volgende PUT-aanvraag werkt bestelling 2 bij. Het gebruikt de ETag van het eerdere GET-antwoord, afgekort op dezelfde manier. De tag identificeert de bestaande weergave, niet de nieuwe aanvraagbody:

   PUT https://api.contoso.com/orders/2 HTTP/1.1
   If-Match: "3097D1FD51082205..."
   Content-Type: application/x-www-form-urlencoded
   Content-Length: 37
   
   productId=3&quantity=5&orderValue=250
   

2. Vergelijk de huidige ETag voor de aangevraagde resource (order 2 in dit voorbeeld) met de voorwaarde If-Match.

   • Als de voorwaarde overeenkomt, voert u de update atomisch uit en retourneert u het gedocumenteerde succesantwoord, zoals 204 (Geen inhoud). Een Location header is niet vereist alleen omdat een bestaande resource is bijgewerkt. Retourneer alleen een ETag in een geslaagd PUT-antwoord wanneer de ETag voldoet aan de validatievereisten van HTTP voor de opgeslagen weergave.

   • Als de voorwaarde niet overeenkomt, retourneert u 412 (Precondition Failed). In dit voorbeeld wordt geen antwoordtekst geretourneerd.

   • Als de resource die moet worden bijgewerkt niet meer bestaat, retourneert u 404 (niet gevonden).

3. Documenteer de geslaagde en conflictreacties, zodat bellers kunnen bepalen of een update is geslaagd of dat ze de huidige weergave moeten ophalen voordat ze een andere wijziging indienen.

Voor bewerkingen die verloren updates moeten voorkomen, moet u een If-Match preconditie vereisen en 428 (Preconditie vereist) retourneren wanneer deze ontbreekt. Gebruik strikte vergelijking bij If-Match.

Als u een versie in het toepassingsgeheugen controleert en vervolgens onvoorwaardelijk opslaat, ontstaat er een racevoorwaarde. Dwing de versievergelijking en de schrijfbewerking atomisch af in de gegevensopslag. Gebruik bijvoorbeeld een database-gelijktijdigheidstoken zodat de update alleen slaagt als de opgeslagen versie nog steeds overeenkomt met de versie die wordt gebruikt om de aanvraag te evalueren.

Configureer in Entity Framework (EF) Core een gelijktijdigheidstoken en ga om met DbUpdateConcurrencyException in plaats van een gelijktijdige wijziging te overschrijven. Vervang in de code voor gegevenstoegang van de API niet automatisch de verwachte versie en/of voer een conflicterende database-update opnieuw uit, tenzij de semantiek van de bewerking dit toestaat. Zie Gelijktijdigheidsconflicten afhandelen voor meer informatie.

Verwerken van grote aanvragen en antwoorden

Grote request- en responsebody's verbruiken API-geheugen, bandbreedte en verbindingscapaciteit. Implementeer streaming- en resourcelimieten zodat grote overdrachten de service niet uitputten. Houd rekening met de volgende punten bij het verwerken van aanzienlijke hoeveelheden gegevens:

Optimaliseer aanvragen en antwoorden die betrekking hebben op grote objecten

Voor grote objecten, zoals afbeeldingen of andere binaire gegevens, ondersteunen streaming-uploads en downloads.

Gebruik asynchrone streaming-API's en laat de server transferframing selecteren voor de onderhandelde HTTP-versie. Voeg niet handmatig toe Transfer-Encoding: chunked aan elk deel van een antwoord. Streaming is niet beperkt tot HTTP/1.1-chunked encoding. Vermijd het bufferen van een volledig onbegrensd verzoek of antwoord in het toepassingsgeheugen.

Stel limieten voor aanvraaginhoud, uploadlimieten, time-outs en annuleringsbeleid in op de toepassings- en hostinglagen. Wijs een te grote aanvraag af met 413 (Inhoud te groot) voordat u het antwoord start.

HTTP-compressie kan de overdrachtsgrootte verminderen, ten koste van extra verwerking op de server en client. Een client kan bijvoorbeeld Accept-Encoding: gzip verzenden. Als de server gzip gecomprimeerde inhoud retourneert, identificeert u de codering met behulp van Content-Encoding: gzip.

Configureer compressie via het hostingplatform of middleware en meet de CPU- en bandbreedte-afwegingen aan zowel de client- als de serverzijde.

• Vermijd het opnieuw comprimeren van indelingen die al zijn gecomprimeerd.
• Voordat u compressie inschakelt voor dynamisch gegenereerde HTTPS-antwoorden, beoordeelt u compressierisico's, zoals BREACH, en past u de juiste oplossingen toe. Zelfs als u HTTPS-compressie uitschakelt in uw middleware, is uw hostingserver mogelijk geconfigureerd om compressie toe te passen.
• Zorg ervoor dat cachevariatie en ETags correct blijven wanneer inhoudscodering verandert.

Zie Responscompressie in ASP.NET Core voor richtlijnen voor de implementatie van compressie en beveiligingsoverwegingen.

Ondersteuning voor gedeeltelijke downloads van grote bronnen

Als de API gedeeltelijke downloads van grote resources ondersteunt, kunt u die mogelijkheid adverteren met Accept-Ranges. Verwerk HEAD-aanvragen door de metagegevens van de resource, inclusief het totale aantal Content-Length, zonder antwoordtekst te retourneren. Voor GET-aanvragen die een ondersteund bytebereik opgeven, retourneert u 206 (gedeeltelijke inhoud), een Content-Length voor het geretourneerde gedeelte en een Content-Range die dat gedeelte van de resource identificeert. Met dit antwoordcontract kunnen aanroepers delen van een resource ophalen zonder dat de API het hele object hoeft te retourneren.

HTTP HEAD-aanvragen en gedeeltelijke antwoorden worden gedetailleerder beschreven in het API-ontwerp.

100-Continue verwerken voor grote uploads

Voor een grote HTTP/1.1-upload kan een client aanvraagheaders verzenden met Expect: 100-continue en wachten voordat de body wordt verzonden. De server kan een tussentijdse reactie van 100 (Continue) verzenden of het verzoek weigeren zonder de volledige berichttekst te ontvangen. Deze uitwisseling maakt deel uit van één aanvraag, geen voorlopige lege aanvraag gevolgd door een tweede volledige aanvraag.

Configureer en test hoe de hostingstack en gateway aanvragen verwerken met en zonder Expect: 100-continue. Controleer het gedrag van de API wanneer deze een upload accepteert of weigert en meet de effecten op het gebruik van serverresources en aanvraaglatentie.

Ondersteuning voor paginering voor aanvragen die grote aantallen objecten kunnen retourneren

Het ophalen van een hele grote verzameling kan de serververwerking, het netwerkverkeer en de latentie verhogen.

Valideer pagineringsinvoer op de server en dwing een maximale paginagrootte af. De volgende controller illustreert de requestvalidatie. Standaard zijn er 10 resultaten en worden limieten buiten 1 tot en met 100 of offsets buiten 0 tot en met 10.000 geweigerd. Deze grenzen zijn illustratief. Kies limieten op basis van de workload en belastingstests. Wanneer u [ApiController] gebruikt, produceren validatiefouten een 400-respons. Zie Web-API's maken met ASP.NET Core voor meer informatie.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrderCollectionsController(IOrderRepository repository) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<IReadOnlyList<Order>>> GetOrders(
        [FromQuery, Range(1, 100)] int limit = 10,
        [FromQuery, Range(0, 10000)] int offset = 0,
        CancellationToken cancellationToken = default)
    {
        var orders = await repository.ListAuthorizedAsync(limit, offset, User, cancellationToken);
        return Ok(orders);
    }
}

Een client kan 30 orders aanvragen vanaf offset 50 met behulp van https://api.contoso.com/orders?limit=30&offset=50.

Naast de aanvraagvalidatie die in het vorige voorbeeld wordt weergegeven, neemt u een koppeling naar de volgende pagina of het vervolgtoken op in het antwoordcontract. Retourneer bijvoorbeeld de orders met een nextLink eigenschap die is ingesteld op https://api.contoso.com/orders?limit=30&offset=80 wanneer een andere pagina beschikbaar is. Behoud filters, sorteervolgorde en API-versie in de koppeling. Laat nextLink weg of stel deze in op null op de laatste pagina. Zie Microsoft Graph paging voor een voorbeeld van een next-link-contract.

Pas filters en paginering toe in de dataopslag, niet na het laden van de hele verzameling. Gebruik een deterministische sorteervolgorde. Voor grote of vaak veranderende verzamelingen evalueer op cursor gebaseerde paginering om dure offsets en instabiele paginagrenzen te voorkomen.

Reactiesnelheid, schaalbaarheid en beschikbaarheid onderhouden

Definieer latentie-, doorvoer- en beschikbaarheidsdoelstellingen voor de kritieke bewerkingen van de API. Ontwerp en test op verwacht verkeer, bursts en uitval van afhankelijkheden. Scale-out en stateless handling ondersteunen deze doelstellingen. Overweeg de volgende implementatievereisten.

Bied asynchrone ondersteuning voor langlopende aanvragen

Voor werk dat langer duurt dan een normale HTTP-aanvraag, valideert en autoriseert u de aanvraag, registreert u het werk duurzaam en retourneert u 202 (geaccepteerd). Vertrouw niet op een niet-bijgehouden in-procestaak om te voltooien na een antwoord: herstarts van de toepassing, inschalen en implementatie kunnen deze onderbreken. Gebruik een duurzame wachtrij en worker of een duurzame workflow wanneer het werk ondanks deze gebeurtenissen moet blijven worden uitgevoerd. Zie het Asynchrone Request-Reply-patroon voor de volledige HTTP-semantiek en implementatierichtlijnen.

Bied een manier voor bellers om de status en het resultaat van de bewerking op te halen. De API kan aanroepers ook op de hoogte stellen wanneer de verwerking is voltooid.

U kunt een statusresource opgeven die clients periodiek opvragen:

1. De cliënt dient de aanvraag in. Valideer de invoer en machtigingen voordat u werk accepteert.
2. Behoud een bewerkings-id en -status in duurzame opslag, zoals Azure-tabelopslag, en zet werk in de wachtrij voor een afzonderlijke processor, bijvoorbeeld met behulp van Azure Service Bus. Coördineer opslag en het in de wachtrij plaatsen, zodat een fout tussen deze twee acties niet leidt tot verlies van geaccepteerd werk.
3. Retourneer 202 met een Location header die het statuseindpunt identificeert en een Retry-After header waarmee de pollingfrequentie wordt bepaald. Accepteer het verzoek pas nadat het werk duurzaam is vastgelegd.
4. Een workerproces verwerkt de bewerking en werkt de duurzame status bij. Maak de verwerking idempotent omdat een worker meer dan één keer hetzelfde werk kan ontvangen. Pas beperkte opnieuw proberen toe op tijdelijke fouten.
5. De client controleert de status-endpoint. Autorisatie op resourceniveau afdwingen voor zowel de status- als resultaateindpunten. Een niet te raden id is geen toestemming.
6. Retourneert een gedocumenteerde statusweergave terwijl het werk in uitvoering is. Geef bij voltooiing het resultaat of een 303-omleiding (See Other) naar een resultaatresource. Rapporteer fouten via een consistent, veilig foutafhandelingscontract.
7. Definieer retentie en opschoning voor bewerkingsrecords en -resultaten. Verloop van documentbewerking, dubbele inzendingen en alle ondersteunde annuleringsfunctionaliteit.

Voor verbonden clients kunt u overwegen ASP.NET Core SignalR te gebruiken voor voltooiingsmeldingen. Houd de duurzame statusresource beschikbaar, zodat clients kunnen herstellen na een verbroken verbinding of een gemiste melding. Zie Overzicht van ASP.NET Core SignalR voor meer informatie.

Zorg ervoor dat elke aanvraag staatloos is

Vereis niet dat een later verzoek dezelfde toepassingsinstantie bereikt als een eerder verzoek. Bewaar de workflow- en resourcestatus in de juiste gedeelde opslaglocaties, niet alleen in het procesgeheugen. Verzoeken kunnen afhankelijk zijn van duurzame resourcestatus zonder serverinstantie-affiniteit te creëren. Statusloze verzoekverwerking ondersteunt uitschalen.

Begrijp uw downstream-afhankelijkheden

Stel een time-out in voor elke downstream-aanroep. Houd de totale tijd voor aanroepen, nieuwe pogingen en vertragingen binnen de deadline van de API-aanvraag en geef annulering van de aanvraag door aan downstreambewerkingen.

Probeer alleen opnieuw bij tijdelijke fouten en bewerkingen die veilig kunnen worden herhaald. Gebruik een beperkt aantal herpogingen met oplopende wachttijd en jitter. Beperk het totale aantal nieuwe pogingen per afhankelijkheid en pogingen per aanvraag. Zie Tijdelijke foutafhandeling voor meer informatie.

Gebruik een circuitbreaker wanneer herhaalde afhankelijkheidsfouten de API-capaciteit kunnen uitputten.

Clients bijhouden en snelheidsbeperking implementeren om de kans op DoS-aanvallen te verminderen

Pas aanvraagsnelheid, gelijktijdigheid, payload en uitvoeringstijdlimieten toe. Verdeel limieten waar mogelijk per geverifieerde beller of tenant. Retourneer 429 (te veel aanvragen) wanneer de client een geconfigureerde aanvraagsnelheid overschrijdt en 503 (Service niet beschikbaar) bij tijdelijke onbeschikbaarheid van de service. Neem Retry-After waar van toepassing. Als de API de aanroepen naar downstreamafhankelijkheden opnieuw probeert uit te voeren, moet u deze nieuwe pogingen beperken, zodat ze de overbelasting niet versterken.

Gateway- en toepassingslimieten dienen verschillende doeleinden. Gatewaylimieten kunnen gedeelde capaciteit beveiligen. Applicatiegrenzen kunnen operationele kosten en downstreamcapaciteit weerspiegelen. Geen van beide vervangt DDoS-beveiliging op de netwerklaag of een webtoepassingsfirewall. Raadpleeg Throttling Pattern voor meer informatie.

Beheer permanente HTTP-verbindingen zorgvuldig

Voor binnenkomende verbindingen configureert u server- en gateway-keep-alive-time-outs, time-outs voor aanvragen en gelijktijdige verbindingslimieten voor de werkbelasting en het netwerkpad. Forceer niet dat verbindingen na elk antwoord worden gesloten. Zie Opties configureren voor de Kestrel-webserver voor informatie over ASP.NET Core-serverinstellingen.

Als de API zelf downstream HTTP-services aanroept, gebruik deze uitgaande verbindingen opnieuw. Gebruik in een .NET API-implementatie langlevende HttpClient-instanties met een geschikte PooledConnectionLifetime, of gebruik clients die zijn gemaakt door IHttpClientFactory. Verwijder uitgaande antwoordberichten en streams wanneer ze niet meer nodig zijn. Deze instellingen zijn van toepassing op de downstreamaanroepen van de API, niet op binnenkomende clientverbindingen. Zie Richtlijnen voor het gebruik van HttpClient voor meer informatie en kanttekeningen bij cookieverwerking.

Publiceren en beheren van een web-API

Rol de API uit in een hostingomgeving die voldoet aan de operationele vereisten. Houd rekening met de volgende strategieën:

• Gebruik HTTPS. Authenticeer aanvragen voor beveiligde eindpunten en dwing autorisatie af voor elke resource en bewerking.
• Schaal de hostingomgeving om te voldoen aan vereisten voor reactietijd wanneer de vraag verandert.
• Meet aanvragen als het factureringsmodel van de API dit vereist.
• Regel verkeer en dwing waar nodig clientquota af.
• Noteer de controlegebeurtenissen die nodig zijn voor naleving en incidentrespons, maar registreer geen inloggegevens, tokens of gevoelige aanvraag- en antwoordteksten.
• Controleer de hoststatus en definieer herstelacties, zoals het opnieuw opstarten van een ongezonde host.

Overweeg om een afzonderlijke façade te gebruiken die gedeelde beheerkwesties afhandelt en gevalideerde aanvragen doorstuurt naar de API. Een gevel kan de volgende mogelijkheden bieden:

• Fungeren als een integratiepunt voor meerdere web-API's.
• Berichten transformeren en vertalen van de communicatieprotocollen voor clients die zijn gebouwd met behulp van verschillende technologieën.
• De belasting van de server die als host fungeert voor de web-API verminderen door aanvragen en antwoorden in de cache op te slaan.

Houd API-contracten en gatewayconfiguratie onder versiebeheer, valideer wijzigingen in deploymentpijplijnen en definieer terugdraaiprocedures. Stem hosting, identiteit, netwerken en governance af op de benadering van de landing zone van de organisatie. Zie Wat is een Azure-landingszone? voor meer informatie.

Een web-API testen

Gebruik eenheidstests om de logica van de API te valideren en integratietests om het HTTP-gedrag te verifiëren.

Neem de volgende controles op:

• Test alle routes om te controleren of ze de juiste bewerkingen aanroepen. Houd er vooral rekening mee dat HTTP-statuscode 405 (methode niet toegestaan) onverwacht wordt geretourneerd. Deze statuscode kan duiden op een onjuiste overeenkomst tussen een route en de HTTP-methoden (GET, POST, PUT, DELETE) die naar die route kunnen worden doorgestuurd.

  Verzend aanvragen die gebruikmaken van methoden die niet door elke afzonderlijke route worden ondersteund en controleer het gedocumenteerde 405-antwoord (methode niet toegestaan) en de Allow-header.

• Controleer of alle routes correct zijn beveiligd en de juiste verificatie en autorisatiecontroles worden uitgevoerd.

  Notitie

  Sommige aspecten van beveiliging, zoals gebruikersverificatie, zijn waarschijnlijk de verantwoordelijkheid van de hostomgeving in plaats van de web-API, maar u moet nog steeds beveiligingstests opnemen als onderdeel van het implementatieproces.

• Test de afhandeling van uitzonderingen die door elke bewerking wordt uitgevoerd en controleer of een geschikt en zinvol HTTP-antwoord wordt doorgegeven aan de clienttoepassing.

• Controleer of de aanvraag- en antwoordberichten goed geformuleerd zijn. Controleer bijvoorbeeld voor een POST-aanvraag waarmee een resource wordt gemaakt deserialisatie, parsering, het maken van een resource en de Location-header van het antwoord.

• Test ondersteunde en niet-ondersteunde mediatypen voor aanvragen afzonderlijk van de contentnegotiatie van antwoorden. Controleer 415-antwoorden (niet-ondersteund mediatype) voor niet-ondersteunde requestformaten en de gedocumenteerde validatiefouten voor ongeldige request-bodies.

• Test elke ondersteunde API-versie, met inbegrip van de routering, aanvraagvalidatie en antwoordschema. Test weggelaten versie-id's, onjuist gevormde versie-id's en niet-ondersteunde versie-id's en controleer of antwoorden in de cache geen versiegrenzen overschrijden.

• Controleer alle koppelingen en URI's in antwoordberichten. Een HTTP POST-bericht moet bijvoorbeeld de URI van de zojuist gemaakte resource retourneren. Alle HATEOAS-koppelingen moeten geldig zijn.

• Zorg ervoor dat elke bewerking de juiste statuscodes voor verschillende invoercombinaties retourneert. Voorbeeld:

  • Als een query is geslaagd, moet de statuscode 200 (OK) worden geretourneerd.
  • Als een resource niet wordt gevonden, moet de bewerking HTTP-statuscode 404 (Niet gevonden) retourneren.
  • Als de client een aanvraag verzendt die een resource verwijdert, moet de statuscode 204 zijn (Geen inhoud).
  • Als de client een aanvraag verzendt waarmee een nieuwe resource wordt gemaakt, moet de statuscode 201 zijn (gemaakt).

  Onderzoek onverwachte 5xx reacties van de toepassing of hostinglaag.

• Test de verschillende combinaties van aanvragen en headers die een clienttoepassing kan opgeven en zorg ervoor dat de web-API de verwachte gegevens retourneert in antwoordberichten.

• Queryreeksen testen. Als een bewerking optionele parameters (zoals pagineringsaanvragen) kan gebruiken, test u de verschillende combinaties en de volgorde van parameters.

• Controleer of de asynchrone bewerkingen zijn voltooid. Controleer voor streamingantwoorden of de API de volledige nettolading niet buffert en clientverbrekingen en annuleringen correct afhandelt. Als de API statusbronnen voor langdurige bewerkingen biedt, controleert u of de voortgang en resultaten van de bewerking correct worden gerapporteerd.

Test de fout- en grensgevallen die van invloed zijn op de juistheid:

• Valideer minimale, maximale, negatieve, onjuist gevormde en overmatige paginering en batchinvoer.
• Volg pagineringskoppelingen tot en met de laatste pagina. Controleer of koppelingen queryopties behouden en of het gedocumenteerde voltooiingssignaal wordt geretourneerd.
• Controleer of aanvullende invoervelden beveiligde eigenschappen niet kunnen wijzigen en dat veldselectie geen onbevoegde gegevens kan weergeven.
• Test overeenkomende, niet-overeenkomende, zwakke, meerdere en jokertekenS ETags en controleer of 304 antwoorden geen hoofdtekst bevatten.
• Voer gelijktijdige updates uit en bevestig dat de gegevensopslag verouderde schrijfbewerkingen atomisch weigert.
• Controleer of bellers de resources, statusrecords of reacties in de cache van een andere beller niet kunnen lezen.
• Voor multitenant-API's test u gesmede of niet-overeenkomende tenant-id's. Wanneer caching is ingeschakeld, test u op aanvragen voor dezelfde resource-URI van verschillende tenants.
• Simuleer time-outs, clientannulering, afhankelijkheidsfouten, workers opnieuw opstarten en dubbele levering van achtergrondwerk.
• Controleer de downstream-time-out en retrybudgetten, annulering en circuitonderbrekerherstel.
• Controleer 429 (te veel aanvragen)- en 503 (service niet beschikbaar)-responses, retrygedrag en de kosten voor het weigeren van overbelaste aanvragen.

Voer belastingstests uit op productieachtige infrastructuur en realistische mixen van workloads. Definieer slaag- en faalcriteria voor doorvoer, latentiepercentielen, foutpercentages en resourceverzadiging. Gebruik Azure Load Testing en integreer regressiecontroles in de implementatiepijplijn.

API Management gebruiken

Overweeg het gebruik van Azure API Management wanneer u een beheerde gateway nodig hebt met het afdwingen van beleid. Hiermee worden kosten, een andere netwerkhop en een afhankelijkheid in het aanvraagpad toegevoegd. Kies een servicelaag en -topologie op basis van capaciteit, netwerken, beschikbaarheid en regionale vereisten; functies verschillen per laag. De Developer-laag is niet bedoeld voor productieworkloads. Volg de Well-Architected-servicerichtlijnen voor API Management.

U kunt een web-API publiceren en beheren door de volgende stappen uit te voeren:

1. Implementeer de web-API op een hostingplatform, zoals Azure App Service, Azure Container Apps, Azure Kubernetes Service (AKS) of Azure Virtuele Machines.

2. Configureer API Management om aanvragen van de gateway-URL naar de back-end-API te routeren. Eén API Management-exemplaar kan aanvragen routeren naar meerdere API's. Meerdere exemplaren kunnen ook dezelfde back-end-API beschikbaar maken wanneer toepassingen verschillende toegangsgrenzen nodig hebben.

   Notitie

   HATEOAS-koppelingen in antwoorden moeten verwijzen naar de URL van de API Management-gateway, niet naar de URL van de back-endserver.

3. Importeer een versiebeheerde OpenAPI-definitie en valideer of de geïmporteerde bewerkingen, parameters, beveiligingsvereisten en antwoordschema's overeenkomen met de implementatie. Controleer ondersteunde OpenAPI-versies en importbeperkingen. Zie Een OpenAPI-specificatie importeren voor meer informatie.

4. Configureer verificatie en autorisatie voor zowel client-naar-gateway- als gateway-naar-back-endcommunicatie. Valideer OAuth 2.0-toegangstokens en dwing de vereiste machtigingen af voor clientaanvragen. Voor back-ends die ondersteuning bieden voor Microsoft Entra ID-authenticatie, geeft u de voorkeur aan een beheerde identiteit van API Management met alleen de machtigingen die nodig zijn. Certificaatverificatie is een andere optie. Vermijd basisverificatie wanneer er veiligere opties beschikbaar zijn. Zie Verificatie en autorisatie voor API's in Azure API Management voor meer informatie.

   Notitie

   Als u API Management-abonnementssleutels nodig hebt, gebruikt u deze niet als vervanging voor verificatie en autorisatie op resourceniveau.

5. Configureer beleidsregels voor verificatie, cross-origin-toegang, berichttransformaties, IP-filtering, frequentielimieten en quota indien nodig. Configureer de cache van antwoorden alleen voor gegevens die veilig in de cache kunnen worden opgeslagen. Pas beleidsregels toe op het juiste toepassingsniveau en controleer de daadwerkelijke werking ervan voor elke bewerking.

Zie de API Management-documentatie voor meer informatie.

Ondersteuning voor ontwikkelaars aan clientzijde

Geef API-gebruikers documentatie voor verificatie, bewerkingen, parameters, gegevenstypen en antwoordcodes.

Documenteer de REST-bewerkingen voor een web-API

Publiceer een OpenAPI-definitie waarin de bewerkingen, parameters, request- en responseschema's en beveiligingsvereisten van de API worden beschreven. Houd het onder versiebeheer met de implementatie en controleer of deze overeenkomt met het werkelijke gedrag van de API.

Vul de API-verwijzing aan met richtlijnen die gebruikers nodig hebben om de API correct te gebruiken:

• Verificatievereisten en machtigingen voor elke bewerking.
• Voorbeeldaanvragen, succesvolle reacties en foutreacties.
• Invoervalidatieregels, payloadlimieten, paginering en frequentielimieten.
• Time-outgedrag, veiligheid bij opnieuw proberen en eventuele idempotentievereisten.
• Status en resultaat ophalen voor langlopende bewerkingen.
• Versiebeheer en compatibiliteitsverwachtingen.

Houd de documentatie en voorbeelden up-to-date wanneer het API-contract wordt gewijzigd.

Een client-SDK implementeren

Overweeg om een SDK te leveren voor API-consumenten. De SDK kan getypte methoden beschikbaar maken waarmee aanvragen worden samengesteld, antwoorden worden geparseerd en de gedocumenteerde fouten van de API worden weergegeven.

U kunt getypte clients genereren op basis van de OpenAPI-definitie van de API, maar het gegenereerde gedrag valideren op basis van de service. Documentverificatie, time-outs, annulering, paginering, foutreacties en welke bewerkingen veilig opnieuw kunnen worden geprobeerd. Houd het compatibiliteitsbeleid voor clients en API's uitgelijnd. Gegenereerde code verwijdert de noodzaak voor integratietests niet.

Een web-API bewaken

Bewaak de API, de bijbehorende afhankelijkheden en elke gateway samen. Definieer serviceniveaudoelstellingen en waarschuwingen op basis van de impact op de klant in plaats van alleen te vertrouwen op hoststatus.

Een web-API rechtstreeks bewaken

Gebruik OpenTelemetry-instrumentatie om traceringen, metrische gegevens en logboeken te verzamelen en de signalen te exporteren naar Application Insights of een andere ondersteunde back-end. Volg voor .NET-, Node.js- en Python-instrumentatie de richtlijnen voor Microsoft OpenTelemetry Distro. Java gebruikt de Azure Monitor OpenTelemetry Distro. Volg de taalspecifieke OpenTelemetry-activeringsrichtlijnen.

Monitorsignalen die API-gedrag beschrijven:

• Aanvraagvolume, foutpercentage en latentie percentielen per bewerking
• Afhankelijkheidslatentie, fouten en time-outs
• Afwijzingen van ratelimieten, gelijktijdig werk en verzadiging van hulpbronnen
• Leeftijd van wachtrij met achtergrondbewerkingen, voltooiingstijd, mislukkingen en nieuwe pogingen
• Cacheeffectiviteit, wanneer caching deel uitmaakt van het ontwerp

De telemetrie die een monitoringtool automatisch verzamelt, varieert afhankelijk van de taal, bibliotheken en configuratie. Instrumentatie toevoegen voor domeinbewerkingen en achtergrondwerk. Ga er niet van uit dat browsersessies, gebruikersrollen of alle aanvraaggegevens automatisch beschikbaar zijn. Traceringscontext doorgeven aan de gateway, toepassing en workers. Configureren van steekproeven en bewaartermijn om de diagnostische behoeften, gegevensgevoeligheid en telemetriekosten in balans te brengen.

Gebruik waar nodig application Insights Standard-beschikbaarheidstests voor terugkerende externe controles. Controleer een zinvol status- of operationeel eindpunt zonder gevoelige gegevens weer te geven, waarschuwingen te definiëren waarop actie kan worden uitgevoerd en een responsrunbook te onderhouden.

Een web-API bewaken met behulp van API Management

Gebruik de Azure Monitor metrische gegevens, logboeken, analyses en diagnostische gegevens die worden ondersteund door API Management om gatewayfouten te onderscheiden van back-endfouten. Gateway- en toepassingstelemetrie correleren en beleidsfouten, capaciteit, latentie van aanvragen en snelheidsbeperking bewaken Beschikbare signalen zijn afhankelijk van het serviceniveau en de gatewayconfiguratie.

Volg de aanbevelingen voor waarneembaarheid en capaciteit in de Well-Architected servicerichtlijnen voor API Management.

Volgende stappen

• overzicht van ASP.NET Core OData beschrijft hoe u REST API-services bouwt die voldoen aan het OData-protocol met behulp van ASP.NET Core.
• ASP.NET Core best practices hebben betrekking op asynchrone I/O, resourcegebruik en responsafhandeling.
• Idempotent Consumer-patroon biedt implementatierichtlijnen voor het bijhouden van verwerkte bericht-id's en het afhandelen van dubbele bezorging.
• HTTP-semantiek definieert HTTP-statuscodes.
• Asynchrone Request-Reply patroon beschrijft duurzaam achtergrondwerk en statusresources.
• Aanbevolen procedures voor Azure API Management-architectuur heeft betrekking op betrouwbaarheid, beveiliging, kosten, bewerkingen en prestaties.
• Azure Load Testing beschrijft loadgeneratie en geautomatiseerde prestatiecontroles.
• OpenTelemetry inschakelen biedt taalspecifieke instrumentatie- en exportrichtlijnen.