Best practices voor RESTful-web-API-ontwerp

Een RESTful-web-API-implementatie is een web-API die architectuurprincipes van Representational State Transfer (REST) gebruikt om een stateless, losjes gekoppelde interface tussen een client en service te bereiken. Een web-API die RESTful is, ondersteunt het standaard HTTP-protocol voor het uitvoeren van bewerkingen op resources en retourneert weergaven van resources die hypermediakoppelingen en HTTP-bewerkingsstatuscodes bevatten.

Een RESTful-web-API moet overeenkomen met de volgende principes:

• Platformafhankelijkheid, wat betekent dat clients de web-API kunnen aanroepen, ongeacht de interne implementatie. De web-API maakt gebruik van HTTP als standaardprotocol om platformafhankelijkheid te bereiken, biedt duidelijke documentatie en ondersteunt een vertrouwde indeling voor gegevensuitwisseling, zoals JSON of XML.

• Losse koppeling, wat betekent dat de client en de webservice onafhankelijk kunnen worden ontwikkeld. De client hoeft de interne implementatie van de webservice niet te kennen en de webservice hoeft de interne implementatie van de client niet te kennen. Als u losse koppeling in een RESTful-web-API wilt bereiken, gebruikt u alleen standaardprotocollen en implementeert u een mechanisme waarmee de client en de webservice akkoord kunnen gaan met de indeling van de gegevens die moeten worden uitgewisseld.

In dit artikel worden aanbevolen procedures beschreven voor het ontwerpen van RESTful-web-API's. Het behandelt ook algemene ontwerppatronen en overwegingen voor het bouwen van web-API's die gemakkelijk te begrijpen, flexibel en onderhoudbaar zijn.

Ontwerpconcepten voor RESTful-web-API's

Als u een RESTful-web-API wilt implementeren, moet u de volgende concepten begrijpen.

• Uniform Resource Identifier (URI): REST API's zijn ontworpen rond resources, die elk soort object, gegevens of service zijn waartoe de client toegang heeft. Elke resource wordt vertegenwoordigd door een URI die die resource op unieke wijze identificeert. De URI voor een bepaalde klantorder kan bijvoorbeeld het volgende zijn:

  https://api.contoso.com/orders/1
  

• Resourceweergave definieert hoe een resource die wordt geïdentificeerd door de URI, wordt gecodeerd en overgebracht via het HTTP-protocol in een specifieke indeling, zoals XML of JSON. Clients die een specifieke resource willen ophalen, moeten de URI van de resource in de aanvraag naar de API gebruiken. De API retourneert een resourceweergave van de gegevens die door de URI worden aangegeven. Een client kan bijvoorbeeld een GET-aanvraag indienen bij de URI-id https://api.contoso.com/orders/1 om de volgende JSON-hoofdtekst te ontvangen:

  {"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}
  

• Een uniforme interface is de manier waarop RESTful-API's losse koppeling tussen client- en service-implementaties realiseren. Voor REST API's die zijn gebouwd op HTTP, bevat de uniforme interface het gebruik van standaard HTTP-werkwoorden voor het uitvoeren van bewerkingen zoals GET, POST, PUT, en PATCHop DELETE resources.

• Stateless request model: RESTful-API's maken gebruik van een staatloos aanvraagmodel, wat betekent dat HTTP-aanvragen onafhankelijk zijn en in elke volgorde kunnen optreden. Daarom is het niet haalbaar om tijdelijke statusinformatie tussen aanvragen te bewaren. De enige plaats waar informatie wordt opgeslagen, bevindt zich in de resources zelf en elke aanvraag moet een atomische bewerking zijn. Een staatloos aanvraagmodel ondersteunt hoge schaalbaarheid omdat er geen affiniteit tussen clients en specifieke servers hoeft te worden bewaard. Het staatloze model kan echter ook de schaalbaarheid beperken vanwege uitdagingen met de schaalbaarheid van back-endopslag van webservices. Zie Gegevenspartitionering voor meer informatie over strategieën voor het uitschalen van een gegevensarchief.

• Hypermedia-koppelingen: REST API's kunnen worden aangestuurd door hypermediakoppelingen die zijn opgenomen in elke resourceweergave. In het volgende codeblok ziet u bijvoorbeeld een JSON-weergave van een order. Het bevat koppelingen voor het ophalen of bijwerken van de klant die is gekoppeld aan de bestelling.

  {
    "orderID":3,
    "productID":2,
    "quantity":4,
    "orderValue":16.60,
    "links": [
      {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"GET" },
      {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"PUT" }
    ]
  }
  

RESTful-web-API-resource-URI's definiëren

Een RESTful-web-API is georganiseerd rond resources. Als u uw API-ontwerp wilt ordenen rond resources, definieert u resource-URI's die zijn toegewezen aan de bedrijfsentiteiten. Indien mogelijk baseer resource-URI's op zelfstandige naamwoorden (de resource) en niet werkwoorden (de bewerkingen op de resource).

In een e-commercesysteem kunnen de primaire bedrijfsentiteiten bijvoorbeeld klanten en orders zijn. Als u een order wilt maken, verzendt een client de ordergegevens in een HTTP POST-aanvraag naar de resource-URI. Het HTTP-antwoord op de aanvraag geeft aan of het maken van de bestelling is geslaagd.

De URI voor het maken van de orderresource kan er ongeveer als volgt uitzien:

https://api.contoso.com/orders // Good

Vermijd het gebruik van werkwoorden in URI's om bewerkingen weer te geven. De volgende URI wordt bijvoorbeeld niet aanbevolen:

https://api.contoso.com/create-order // Avoid

Entiteiten worden vaak gegroepeerd in verzamelingen zoals klanten of orders. Een verzameling is een afzonderlijke resource van de items in de verzameling, dus deze moet een eigen URI hebben. De volgende URI kan bijvoorbeeld de verzameling orders vertegenwoordigen:

https://api.contoso.com/orders

Nadat de client de verzameling heeft opgehaald, kan deze een GET-aanvraag indienen bij de URI van elk item. Als u bijvoorbeeld informatie over een specifieke order wilt ontvangen, voert de client een HTTP GET-aanvraag uit op de URI https://api.contoso.com/orders/1 om de volgende JSON-hoofdtekst te ontvangen als resourceweergave van de interne ordergegevens:

{"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}

Naamconventies voor resource-URI's

Wanneer u een RESTful-web-API ontwerpt, is het belangrijk dat u de juiste naamgevings- en relatieconventies gebruikt voor resources:

• Gebruik zelfstandige naamwoorden voor resource-namen. Gebruik zelfstandige naamwoorden om resources weer te geven. Gebruik bijvoorbeeld /orders in plaats van /create-order. De METHODEN HTTP GET, POST, PUT, PATCH en DELETE impliceren al de mondelinge actie.

• Gebruik meervoud zelfstandige naamwoorden om verzamelings-URI's te noemen. Over het algemeen helpt het om meervoud zelfstandige naamwoorden te gebruiken voor URI's die verwijzen naar verzamelingen. Het is een goede gewoonte om URI's voor verzamelingen en items in een hiërarchie te organiseren. Bijvoorbeeld, /customers is het pad naar de verzameling van de klant, en /customers/5 is het pad naar de klant met een ID die gelijk is aan 5. Deze aanpak helpt de web-API intuïtief te houden. Bovendien kunnen veel web-API-frameworks aanvragen routeren op basis van geparameteriseerde URI-paden, zodat u een route voor het pad /customers/{id}kunt definiëren.

• Houd rekening met de relaties tussen verschillende typen resources en hoe u deze koppelingen mogelijk beschikbaar maakt. Het kan bijvoorbeeld /customers/5/orders alle orders voor klant 5 vertegenwoordigen. U kunt de relatie ook vanuit de andere richting benaderen door de koppeling van een order aan een klant uit te drukken. In dit scenario kan de URI zijn /orders/99/customer. Het uitbreiden van dit model kan echter lastig worden om te implementeren. Een betere benadering is het opnemen van koppelingen in de hoofdtekst van het HTTP-antwoordbericht, zodat clients eenvoudig toegang hebben tot gerelateerde resources. Gebruik Hypertext als de Engine of Application State (HATEOAS) om navigatie naar gerelateerde resources mogelijk te maken . Dit mechanisme wordt in meer detail beschreven.

• Houd relaties eenvoudig en flexibel. In complexere systemen bent u misschien geneigd om URI's te bieden waarmee de client door verschillende niveaus van relaties kan navigeren, zoals /customers/1/orders/99/products. Dit complexiteitsniveau kan echter moeilijk te onderhouden zijn en is inflexibel als de relaties tussen resources in de toekomst veranderen. Probeer in plaats daarvan URI's relatief eenvoudig te houden. Nadat een toepassing een verwijzing naar een resource heeft, moet u deze verwijzing kunnen gebruiken om items te vinden die betrekking hebben op die resource. U kunt de voorgaande query vervangen door de URI /customers/1/orders om alle orders voor klant 1 te vinden en vervolgens te gebruiken /orders/99/products om de producten in deze bestelling te vinden.

  Hint

  Vermijd het vereisen van resource-URI's die complexer zijn dan verzameling/item/verzameling.

• Vermijd een groot aantal kleine hulpmiddelen. Alle webaanvragen leggen een belasting op de webserver op. Hoe meer aanvragen, hoe groter de belasting. Web-API's die een groot aantal kleine resources beschikbaar maken, worden chatty web-API's genoemd. Probeer deze API's te vermijden omdat ze een clienttoepassing nodig hebben om meerdere aanvragen te verzenden om alle gegevens te vinden die hiervoor nodig zijn. Overweeg in plaats daarvan denormaliseren van de gegevens en het combineren van gerelateerde informatie in grotere resources die kunnen worden opgehaald via één aanvraag. U moet deze aanpak echter nog steeds verdelen tegen de overhead van het ophalen van gegevens die de client niet nodig heeft. Bij het ophalen van grote objecten kan de latentie van een aanvraag toenemen en meer bandbreedtekosten in rekening worden gebracht. Zie Chatty I/O en Overbodig ophalen voor meer informatie over deze prestatie-antipatronen.

• Vermijd het maken van API's die de interne structuur van een database weerspiegelen. Het doel van REST is het modelleren van bedrijfsentiteiten en de bewerkingen die een toepassing op deze entiteiten kan uitvoeren. Een client mag niet worden blootgesteld aan de interne implementatie. Als uw gegevens bijvoorbeeld zijn opgeslagen in een relationele database, hoeft de web-API elke tabel niet beschikbaar te maken als een verzameling resources. Deze aanpak verhoogt de kwetsbaarheid voor aanvallen en kan leiden tot gegevenslekken. In plaats daarvan kunt u de web-API beschouwen als een abstractie van de database. Introduceer zo nodig een toewijzingslaag tussen de database en de web-API. Deze laag zorgt ervoor dat clienttoepassingen worden geïsoleerd van wijzigingen in het onderliggende databaseschema.

RESTful-web-API-methoden definiëren

RESTful-web-API-methoden zijn afgestemd op de aanvraagmethoden en mediatypen die zijn gedefinieerd door het HTTP-protocol. In deze sectie worden de meest voorkomende aanvraagmethoden en de mediatypen beschreven die worden gebruikt in RESTful-web-API's.

HTTP-aanvraagmethoden

Het HTTP-protocol definieert veel aanvraagmethoden die aangeven welke actie u wilt uitvoeren op een resource. De meest voorkomende methoden die worden gebruikt in RESTful-web-API's zijn GET, POST, PUT, PATCH en DELETE. Elke methode komt overeen met een specifieke bewerking. Wanneer u een RESTful-web-API ontwerpt, gebruikt u deze methoden op een manier die consistent is met de protocoldefinitie, de resource die wordt geopend en de actie die wordt uitgevoerd.

Het is belangrijk om te onthouden dat het effect van een specifieke aanvraagmethode afhankelijk moet zijn van of de resource een verzameling of een afzonderlijk item is. De volgende tabel bevat enkele conventies die de meeste RESTful-implementaties gebruiken.

GET-aanvragen

Met een GET-aanvraag wordt een weergave van de resource opgehaald op de opgegeven URI. De hoofdtekst van het antwoordbericht bevat de details van de aangevraagde resource.

Een GET-aanvraag moet een van de volgende HTTP-statuscodes retourneren:

POST-aanvragen

Een POST-aanvraag moet een bron creëren. De server wijst een URI toe voor de nieuwe resource en retourneert die URI aan de client.

In een RESTful-model worden POST-aanvragen gebruikt om een nieuwe resource toe te voegen aan de verzameling die de URI identificeert. Een POST-aanvraag kan echter ook worden gebruikt om gegevens te verzenden voor verwerking naar een bestaande resource, zonder dat er een nieuwe resource wordt gemaakt.

Een POST-aanvraag moet een van de volgende HTTP-statuscodes retourneren:

PUT-aanvraag

Een PUT-aanvraag moet een bestaande resource bijwerken als deze bestaat of, in sommige gevallen, een nieuwe resource maken als deze niet bestaat. Een PUT-aanvraag indienen:

1. De client geeft de URI voor de resource op en bevat een aanvraagbody die een volledige weergave van de resource bevat.
2. De client doet de aanvraag.
3. Als er al een resource met deze URI bestaat, wordt deze vervangen. Anders wordt er een nieuwe resource gemaakt als de route deze ondersteunt.

PUT-methoden worden toegepast op resources die afzonderlijke items zijn, zoals een specifieke klant, in plaats van verzamelingen. Een server kan updates ondersteunen, maar niet maken via PUT. Of het maken via PUT moet worden ondersteund, is afhankelijk van of de client een URI zinvol en betrouwbaar kan toewijzen aan een resource voordat deze bestaat. Als dat niet lukt, gebruikt u POST om resources te maken en de server de URI toe te wijzen. Gebruik vervolgens PUT of PATCH om de URI bij te werken.

Een PUT-aanvraag moet een van de volgende HTTP-statuscodes retourneren:

PATCH-aanvragen

Een PATCH-aanvraag voert een gedeeltelijke update uit naar een bestaande resource. De client geeft de URI voor de resource op. De hoofdtekst van de aanvraag geeft een set wijzigingen op die moeten worden toegepast op de resource. Deze methode kan efficiënter zijn dan het gebruik van PUT-aanvragen, omdat de client alleen de wijzigingen verzendt en niet de volledige weergave van de resource. PATCH kan ook een nieuwe resource maken door een set updates op te geven voor een lege of null-resource als de server deze actie ondersteunt.

Met een PATCH-aanvraag verzendt de client een set updates naar een bestaande resource in de vorm van een patchdocument. De server verwerkt het patchdocument om de update uit te voeren. In het patchdocument wordt alleen een set wijzigingen opgegeven die moeten worden toegepast in plaats van de hele resource te beschrijven. De specificatie voor de PATCH-methode , RFC 5789, definieert geen specifieke indeling voor patchdocumenten. De indeling moet worden afgeleid van het mediatype in de aanvraag.

JSON is een van de meest voorkomende gegevensindelingen voor web-API's. De twee belangrijkste patchindelingen op basis van JSON zijn JSON-patch en JSON-samenvoegpatch.

De JSON-samenvoegpatch is eenvoudiger dan de JSON-patch. Het patchdocument heeft dezelfde structuur als de oorspronkelijke JSON-resource, maar bevat alleen de subset velden die moeten worden gewijzigd of toegevoegd. Daarnaast kan een veld worden verwijderd door op te null geven voor de veldwaarde in het patchdocument. Deze specificatie betekent dat samenvoegpatch niet geschikt is als de oorspronkelijke resource expliciete null-waarden kan hebben.

Stel dat de oorspronkelijke resource de volgende JSON-weergave heeft:

{
    "name":"gizmo",
    "category":"widgets",
    "color":"blue",
    "price":10
}

Hier volgt een mogelijke JSON-samenvoegpatch voor deze resource:

{
    "price":12,
    "color":null,
    "size":"small"
}

Deze samenvoegpatch geeft de server de opdracht om bij te werken price, te verwijderen coloren toe te voegen size. De waarden voor name en category worden niet gewijzigd. Zie RFC 7396 voor meer informatie over de JSON-samenvoegpatch. Het mediatype voor JSON merge patch is application/merge-patch+json.

De merge-patch is niet geschikt als de oorspronkelijke bron expliciete null-waarden kan bevatten vanwege de speciale betekenis van null in het patchdocument. Het patchdocument geeft ook niet de volgorde op waarin de server de updates moet toepassen. Of deze volgorde van belang is, is afhankelijk van de gegevens en het domein. JSON-patch, gedefinieerd in RFC 6902, is flexibeler omdat hiermee de wijzigingen worden opgegeven als een reeks bewerkingen die moeten worden toegepast, waaronder toevoegen, verwijderen, vervangen, kopiëren en testen om waarden te valideren. Het mediatype voor JSON-patch is application/json-patch+json.

Een PATCH-aanvraag moet een van de volgende HTTP-statuscodes retourneren:

DELETE-aanvragen

Met een DELETE-aanvraag wordt de resource verwijderd op de opgegeven URI. Een DELETE-aanvraag moet een van de volgende HTTP-statuscodes retourneren:

Resource MIME-typen

Representatie van een bron is de manier waarop een resource, die wordt geïdentificeerd door de URI, wordt gecodeerd en getransporteerd via het HTTP-protocol in een specifieke indeling, zoals XML of JSON. Clients die een specifieke resource willen ophalen, moeten de URI in de aanvraag gebruiken voor de API. De API reageert door een resourceweergave te retourneren van de gegevens die worden aangegeven door de URI.

In het HTTP-protocol worden resourceweergave-indelingen opgegeven met behulp van mediatypen, ook wel MIME-typen genoemd. Voor niet-binaire gegevens ondersteunen de meeste web-API's JSON (mediatype = application/json) en mogelijk XML (mediatype = application/xml).

De header Inhoudstype in een aanvraag of antwoord geeft de indeling van de resourceweergave aan. In het volgende voorbeeld ziet u een POST-aanvraag die JSON-gegevens bevat:

POST https://api.contoso.com/orders
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

Als de server het mediatype niet ondersteunt, moet de HTTP-statuscode 415 (niet-ondersteund mediatype) worden geretourneerd.

Een clientaanvraag kan een Accept-header bevatten die een lijst met mediatypen bevat die de client accepteert van de server in het antwoordbericht. Voorbeeld:

GET https://api.contoso.com/orders/2
Accept: application/json, application/xml

Als de server niet overeenkomt met een van de vermelde mediatypen, moet deze HTTP-statuscode 406 retourneren (niet acceptabel).

Asynchrone methoden implementeren

Soms is voor een POST-, PUT-, PATCH- of DELETE-methode mogelijk verwerking vereist die enige tijd kost. Als u wacht op voltooiing voordat u een antwoord naar de client verzendt, kan dit een onaanvaardbare latentie veroorzaken. In dit scenario kunt u overwegen de methode asynchroon te maken. Een asynchrone methode moet HTTP-statuscode 202 (Geaccepteerd) retourneren om aan te geven dat de aanvraag is geaccepteerd voor verwerking, maar onvolledig is.

Maak een eindpunt beschikbaar dat de status van een asynchrone aanvraag retourneert, zodat de client de status kan controleren door het statuseindpunt te peilen. Neem de URI van het statuseindpunt op in de locatieheader van het 202-antwoord. Voorbeeld:

HTTP/1.1 202 Accepted
Location: /api/status/12345

Als de client een GET-aanvraag naar dit eindpunt verzendt, moet het antwoord de huidige status van de aanvraag bevatten. Optioneel kan het een geschatte tijd tot voltooiing of een koppeling bevatten om de bewerking te annuleren.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}

Als met de asynchrone bewerking een nieuwe resource wordt gemaakt, moet het statuseindpunt statuscode 303 (Zie overige) retourneren nadat de bewerking is voltooid. Neem in het 303-antwoord een locatieheader op die de URI van de nieuwe resource geeft:

HTTP/1.1 303 See Other
Location: /api/orders/12345

Zie Asynchrone ondersteuning bieden voor langlopende aanvragen en Asynchrone Request-Reply patroon voor meer informatie.

Paginering en filteren van gegevens implementeren

Om gegevensophaling te optimaliseren en de belasting te verkleinen, implementeer gegevenspaginering en query-gebaseerde filtering in uw API-ontwerp. Met deze technieken kunnen clients alleen de subset van de gegevens aanvragen die ze nodig hebben, waardoor de prestaties kunnen worden verbeterd en het bandbreedtegebruik kan worden verminderd.

• Paginering verdeelt grote gegevenssets in kleinere, beheerbare segmenten. Gebruik queryparameters zoals limit het opgeven van het aantal items dat moet worden geretourneerd en offset om het beginpunt op te geven. Zorg ervoor dat u ook zinvolle standaardwaarden voor limit en offset, zoals limit=25 en offset=0, opgeeft. Voorbeeld:

  GET /orders?limit=25&offset=50
  

  • limit: Hiermee geeft u het maximum aantal items dat moet worden geretourneerd.

    Hint

    Als u denial-of-service-aanvallen wilt voorkomen, kunt u overwegen om een bovengrens op te leggen voor het aantal geretourneerde items. Als uw servicesets max-limit=25en clientaanvragen limit=1000bijvoorbeeld zijn ingesteld, kan uw service 25 items of een HTTP-BAD-REQUEST-fout retourneren, afhankelijk van de API-documentatie.

  • offset: Hiermee geeft u de beginindex voor de gegevens op.

• Door te filteren kunnen clients de gegevensset verfijnen door voorwaarden toe te passen. Met de API kan de client het filter doorgeven in de querytekenreeks van de URI:

  GET /orders?minCost=100&status=shipped
  

  • minCost: Filtert orders met een minimale kosten van 100.
  • status: Filtert orders met een specifieke status.

Houd rekening met de volgende best practices:

• Door te sorteren kunnen clients gegevens sorteren met behulp van een sort parameter zoals sort=price.

  Belangrijk

  De sorteerbenadering kan een negatief effect hebben op caching omdat queryreeksparameters deel uitmaken van de resource-id die veel cache-implementaties gebruiken als sleutel voor gegevens in de cache.

• Met veldselectie voor door de client gedefinieerde projecties kunnen clients alleen de velden opgeven die ze nodig hebben met behulp van een fields parameter zoals fields=id,name. U kunt bijvoorbeeld een queryreeksparameter gebruiken die een door komma's gescheiden lijst met velden accepteert, zoals /orders?fields=ProductID, Quantity.

Uw API moet de aangevraagde velden valideren om ervoor te zorgen dat de client toegang tot deze velden heeft en geen velden beschikbaar maakt die normaal gesproken niet beschikbaar zijn via de API.

Gedeeltelijke antwoorden ondersteunen

Sommige resources bevatten grote binaire velden, zoals bestanden of afbeeldingen. Als u problemen wilt oplossen die worden veroorzaakt door onbetrouwbare en onregelmatige verbindingen en om de reactietijden te verbeteren, kunt u overwegen om het gedeeltelijke ophalen van grote binaire resources te ondersteunen.

Ter ondersteuning van gedeeltelijke antwoorden moet de web-API de Accept-Ranges-header voor GET-aanvragen voor grote resources ondersteunen. Deze header geeft aan dat de GET-bewerking gedeeltelijke aanvragen ondersteunt. De clienttoepassing kan GET-aanvragen indienen die een subset van een resource retourneren, die is opgegeven als een bereik van bytes.

Overweeg ook om HTTP HEAD-aanvragen voor deze resources te implementeren. Een HEAD-aanvraag is vergelijkbaar met een GET-aanvraag, behalve dat deze alleen de HTTP-headers retourneert die de resource beschrijven, met een lege berichttekst. Een clienttoepassing kan een HEAD-aanvraag uitgeven om te bepalen of een resource moet worden opgehaald met behulp van gedeeltelijke GET-aanvragen. Voorbeeld:

HEAD https://api.contoso.com/products/10?fields=productImage

Hier volgt een voorbeeld van een antwoordbericht:

HTTP/1.1 200 OK

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

De header Content-Length geeft de totale grootte van de resource en de Accept-Ranges header geeft aan dat de bijbehorende GET-bewerking gedeeltelijke resultaten ondersteunt. De clienttoepassing kan deze informatie gebruiken om de afbeelding op te halen in kleinere segmenten. Door het eerste verzoek worden de eerste 2500 bytes opgehaald door gebruik te maken van de Range-header.

GET https://api.contoso.com/products/10?fields=productImage
Range: bytes=0-2499

Het antwoordbericht geeft aan dat dit antwoord gedeeltelijk is door HTTP-statuscode 206 te retourneren. De header Content-Length geeft het werkelijke aantal bytes op dat wordt geretourneerd in de berichttekst en niet de grootte van de resource. De header Inhoudsbereik geeft aan welk deel van de resource wordt geretourneerd (bytes 0-2499 van 4580):

HTTP/1.1 206 Partial Content

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580

[...]

Een volgende aanvraag van de clienttoepassing kan de rest van de resource ophalen.

HATEOAS implementeren

Een van de belangrijkste redenen voor het gebruik van REST is de mogelijkheid om door de hele set resources te navigeren zonder voorafgaande kennis van het URI-schema. Elke HTTP GET-aanvraag moet de informatie retourneren die nodig is om de resources te vinden die rechtstreeks zijn gerelateerd aan het aangevraagde object via hyperlinks die zijn opgenomen in het antwoord. De aanvraag moet ook worden voorzien van informatie die de bewerkingen beschrijft die beschikbaar zijn voor elk van deze resources. Dit principe wordt HATEOAS of Hypertext genoemd als de engine van de toepassingsstatus. Het systeem is effectief een eindige statusmachine en de reactie op elke aanvraag bevat de informatie die nodig is om van de ene status naar de andere te gaan. Er mag geen andere informatie nodig zijn.

Als u bijvoorbeeld de relatie tussen een order en een klant wilt afhandelen, kan de weergave van een order koppelingen bevatten waarmee de beschikbare bewerkingen voor de klant van de order worden geïdentificeerd. Het volgende codeblok is een mogelijke weergave:

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"DELETE",
      "types":[]
    }]
}

In dit voorbeeld bevat de links matrix een set koppelingen. Elke koppeling vertegenwoordigt een bewerking op een gerelateerde entiteit. De gegevens voor elke koppeling bevatten de relatie (klant), de URI (https://api.contoso.com/customers/3), de HTTP-methode en de ondersteunde MIME-typen. De clienttoepassing heeft deze informatie nodig om de bewerking aan te roepen.

De links matrix bevat ook zelfverwijzende informatie over de opgehaalde resource. Deze koppelingen hebben de relatie zelf.

De set koppelingen die worden geretourneerd, kan veranderen, afhankelijk van de status van de resource. Het idee dat hypertext de engine van de toepassingsstatus is, beschrijft dit scenario.

Versiebeheer implementeren

Een web-API blijft niet statisch. Naarmate de bedrijfsvereisten veranderen, worden er nieuwe verzamelingen resources toegevoegd. Wanneer er nieuwe resources worden toegevoegd, kunnen de relaties tussen resources veranderen en kan de structuur van de gegevens in resources worden gewijzigd. Het bijwerken van een web-API voor het afhandelen van nieuwe of andere vereisten is een eenvoudig proces, maar u moet rekening houden met de effecten die dergelijke wijzigingen hebben op clienttoepassingen die gebruikmaken van de web-API. De ontwikkelaar die een web-API ontwerpt en implementeert, heeft volledige controle over die API, maar ze hebben niet dezelfde mate van controle over clienttoepassingen die zijn gebouwd door partnerorganisaties. Het is belangrijk om bestaande clienttoepassingen te blijven ondersteunen, terwijl nieuwe clienttoepassingen nieuwe functies en resources kunnen gebruiken.

Een web-API die versiebeheer implementeert, kan wijzen op de functies en resources die worden weergegeven. Een clienttoepassing kan aanvragen indienen die zijn gericht op een specifieke versie van een functie of resource. In de volgende secties worden verschillende benaderingen beschreven, die elk hun eigen voordelen en afwegingen hebben.

Geen versiebeheer

Deze benadering is het eenvoudigst en kan voor sommige interne API's werken. Belangrijke wijzigingen kunnen worden weergegeven als nieuwe resources of nieuwe koppelingen. Het toevoegen van inhoud aan bestaande resources kan geen belangrijke wijziging opleveren omdat clienttoepassingen die deze inhoud niet verwachten te zien, deze negeren.

Een aanvraag bij de URI https://api.contoso.com/customers/3 moet bijvoorbeeld de details retourneren van één klant die de id, nameen address velden bevat die de clienttoepassing verwacht:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Als het DateCreated veld wordt toegevoegd aan het schema van de klantresource, ziet het antwoord er als volgt uit:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":"1 Microsoft Way Redmond WA 98053"}

Bestaande clienttoepassingen blijven mogelijk correct functioneren als ze niet-herkende velden kunnen negeren. Ondertussen kunnen nieuwe clienttoepassingen worden ontworpen om dit nieuwe veld te verwerken. Echter, meer drastische wijzigingen in het schema van resources, waaronder veldverwijderingen of hernoemen, kunnen zich voordoen. Of de relaties tussen hulpmiddelen kunnen wellicht veranderen. Deze updates kunnen belangrijke wijzigingen zijn die verhinderen dat bestaande clienttoepassingen correct werken. Houd in deze scenario's rekening met een van de volgende methoden:

• Versiebeheer van URI
• Versiebeheer van queryreeksen
• Versiebeheer van headers
• Versiebeheer van mediatypen

Versiebeheer van URI

Telkens wanneer u de web-API wijzigt of het schema van resources wijzigt, voegt u een versienummer toe aan de URI voor elke resource. De eerder bestaande URI's moeten normaal blijven functioneren door resources te retourneren die voldoen aan hun oorspronkelijke schema.

Het veld in het vorige voorbeeld wordt bijvoorbeeld address geherstructureerd in subvelden die elk onderdeel van het adres bevatten, zoals streetAddress, city, stateen zipCode. Deze versie van de resource kan worden weergegeven via een URI die een versienummer bevat, zoals https://api.contoso.com/v2/customers/3:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Dit versiebeheermechanisme is eenvoudig, maar is afhankelijk van de server om de aanvraag naar het juiste eindpunt te routeren. Het kan echter onhandig worden naarmate de web-API door verschillende iteraties wordt ontwikkeld en de server veel verschillende versies moet ondersteunen. Vanuit het oogpunt van een purist halen de clienttoepassingen in alle gevallen dezelfde gegevens op (klant 3), zodat de URI niet moet verschillen op basis van de versie. Dit schema bemoeilijkt ook de implementatie van HATEOAS, omdat alle koppelingen het versienummer in hun URI's moeten opnemen.

Versiebeheer van queryreeksen

In plaats van meerdere URI's op te geven, kunt u de versie van de resource opgeven met behulp van een parameter in de queryreeks die is toegevoegd aan de HTTP-aanvraag, zoals https://api.contoso.com/customers/3?version=2. De versieparameter moet standaard een zinvolle waarde hebben, zoals 1, als oudere clienttoepassingen deze weglaten.

Deze benadering heeft het semantische voordeel dat dezelfde resource altijd wordt opgehaald uit dezelfde URI. Deze methode is echter afhankelijk van de code die de aanvraag verwerkt om de querytekenreeks te parseren en het juiste HTTP-antwoord terug te sturen. Deze aanpak bemoeilijkt ook de implementatie van HATEOAS op dezelfde manier als het URI-versiebeheermechanisme.

Versiebeheer van headers

In plaats van het versienummer toe te voegen als een querytekenreeksparameter, kunt u een aangepaste header implementeren die de versie van de resource aangeeft. Deze aanpak vereist dat de clienttoepassing de juiste header toevoegt aan aanvragen. De code die de clientaanvraag verwerkt, kan echter een standaardwaarde gebruiken, zoals versie 1, als de versieheader wordt weggelaten.

In de volgende voorbeelden wordt een aangepaste header met de naam Custom-Header gebruikt. De waarde van deze header geeft de versie van de web-API aan.

Versie 1:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Versie 2:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Net als bij versiebeheer van URI's en het versiebeheer van queryreeksen, moet u de juiste aangepaste header opnemen in koppelingen om HATEOAS te implementeren.

Versiebeheer van mediatypen

Wanneer een clienttoepassing een HTTP GET-aanvraag naar een webserver verzendt, moet deze een Accept-header gebruiken om de indeling op te geven van de inhoud die deze kan verwerken. Meestal is het doel van de accept-header om de clienttoepassing te laten opgeven of de hoofdtekst van het antwoord XML, JSON of een andere algemene indeling moet zijn die de client kan parseren. Het is echter mogelijk om aangepaste mediatypen te definiëren die informatie bevatten waarmee de clienttoepassing kan aangeven welke versie van een resource wordt verwacht.

In het volgende voorbeeld ziet u een aanvraag waarmee een accept-header met de waarde application/vnd.contoso.v1+jsonwordt opgegeven. Het vnd.contoso.v1 element geeft aan aan de webserver dat versie 1 van de resource moet worden geretourneerd. Het json element geeft aan dat de indeling van de antwoordtekst JSON moet zijn:

GET https://api.contoso.com/customers/3
Accept: application/vnd.contoso.v1+json

De code die de aanvraag verwerkt, is verantwoordelijk voor het verwerken van de Accept-header en deze zoveel mogelijk respecteren. De clienttoepassing kan meerdere indelingen opgeven in de header Accepteren, zodat de webserver de meest geschikte indeling kan kiezen voor de hoofdtekst van het antwoord. De webserver bevestigt de indeling van de gegevens in de hoofdtekst van het antwoord met behulp van de header Content-Type:

HTTP/1.1 200 OK
Content-Type: application/vnd.contoso.v1+json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Als de header Accepteren geen bekende mediatypen opgeeft, kan de webserver een HTTP 406-antwoordbericht (Niet acceptabel) genereren of een bericht retourneren met een standaardmediatype.

Dit versiebeheermechanisme is eenvoudig en goed geschikt voor HATEOAS, waarbij het MIME-type van gerelateerde gegevens in resourcekoppelingen kan worden opgenomen.

Multitenant-web-API's

Een web-API-oplossing voor meerdere tenants wordt gedeeld door meerdere tenants, zoals afzonderlijke organisaties die hun eigen groepen gebruikers hebben.

Multitenancy beïnvloedt het ontwerp van web-API aanzienlijk, omdat hiermee wordt bepaald hoe resources worden geopend en gedetecteerd in meerdere tenants binnen één web-API. Ontwerp een API met multitenancy in gedachten om toekomstige herstructurering te voorkomen om isolatie, schaalbaarheid of tenantspecifieke aanpassingen te implementeren.

Een goed ontworpen API moet duidelijk definiëren hoe tenants worden geïdentificeerd in aanvragen, hetzij via subdomeinen, paden, headers of tokens. Deze structuur zorgt voor een consistente maar flexibele ervaring voor alle gebruikers binnen het systeem. Zie Toewijzingsaanvragen aan tenants in een multitenant-oplossing voor meer informatie.

Multitenancy is van invloed op eindpuntstructuur, aanvraagafhandeling, verificatie en autorisatie. Deze aanpak beïnvloedt ook hoe API-gateways, load balancers en back-endservices aanvragen routeren en verwerken. De volgende strategieën zijn veelvoorkomende manieren om multitenancy in een web-API te bereiken.

Subdomein- of domeingebaseerde isolatie gebruiken (beheer op DNS-niveau)

Met deze benadering worden aanvragen gerouteerd met behulp van tenantspecifieke domeinen. Wildcarddomeinen maken gebruik van subdomeinen voor flexibiliteit en eenvoud. Aangepaste domeinen, waarmee tenants hun eigen domeinen kunnen gebruiken, bieden meer controle en kunnen worden afgestemd op specifieke behoeften. Beide methoden zijn afhankelijk van de juiste DNS-configuratie, inclusief A en CNAME records, om verkeer naar de juiste infrastructuur te leiden. Wildcarddomeinen vereenvoudigen de configuratie, maar aangepaste domeinen bieden een betere merkervaring.

Behoud de hostnaam tussen de reverse proxy en back-endservices om problemen zoals URL-doorverwijzing te vermijden en te voorkomen dat interne URL's worden blootgesteld. Deze methode zorgt voor een juiste routering van tenantspecifiek verkeer en helpt interne infrastructuur te beveiligen. DNS-omzetting is van cruciaal belang voor het bereiken van gegevensresidency en het waarborgen van regelgeving.

GET https://adventureworks.api.contoso.com/orders/3

Tenantspecifieke HTTP-headers doorgeven

Tenantgegevens kunnen worden doorgegeven via aangepaste HTTP-headers, zoals X-Tenant-ID of X-Organization-ID via hostheaders, zoals Host of X-Forwarded-Host, of kunnen worden geëxtraheerd uit JSON-webtokenclaims (JWT). De keuze hangt af van de routeringsmogelijkheden van uw API-gateway of reverse proxy, waarbij op headers gebaseerde oplossingen een Layer 7-gateway (L7) vereisen om elk verzoek te inspecteren. Deze vereiste voegt verwerkingsoverhead toe, waardoor de rekenkosten stijgen wanneer het verkeer groeit. Isolatie op basis van headers biedt echter belangrijke voordelen. Het maakt gecentraliseerde verificatie mogelijk, wat het beveiligingsbeheer voor multitenant-API's vereenvoudigt. Door SDK's of API-clients te gebruiken, wordt tenantcontext dynamisch beheerd tijdens runtime, wat de complexiteit van de configuratie aan de clientzijde vermindert. Het behouden van tenantcontext in headers resulteert ook in een schoner, meer RESTful API-ontwerp door tenantspecifieke gegevens in de URI te vermijden.

Een belangrijke overweging voor routering op basis van headers is dat caching ingewikkeld is, met name wanneer cachelagen uitsluitend afhankelijk zijn van op URI gebaseerde sleutels en geen rekening houden met headers. Omdat de meeste cachemechanismen optimaliseren voor URI-zoekacties, kan het vertrouwen op headers leiden tot gefragmenteerde cachevermeldingen. Gefragmenteerde vermeldingen verminderen cachetreffers en verhogen de back-endbelasting. Belangrijker is dat als een cachelaag geen onderscheid maakt tussen reacties op headers, deze gegevens in de cache kunnen leveren die bedoeld zijn voor de ene tenant naar de andere en risico lopen op gegevenslekken.

GET https://api.contoso.com/orders/3
X-Tenant-ID: adventureworks

of

GET https://api.contoso.com/orders/3
Host: adventureworks

of

GET https://api.contoso.com/orders/3
Authorization: Bearer <JWT-token including a tenant-id: adventureworks claim>

Tenantspecifieke informatie doorgeven via het URI-pad

Met deze methode worden tenant-id's in de resourcehiërarchie toegevoegd, en het is afhankelijk van de API-gateway of omgekeerde proxy om op basis van het padsegment de juiste tenant te bepalen. Isolatie op basis van paden is effectief, maar het maakt inbreuk op het RESTful-ontwerp van de web-API en introduceert complexere routeringslogica. Het vereist vaak patroonkoppeling of reguliere expressies om het URI-pad te parseren en canonicaliseren.

Isolatie op basis van headers brengt daarentegen tenantgegevens over via HTTP-headers als sleutel-waardeparen. Beide benaderingen maken efficiënt delen van infrastructuur mogelijk om de operationele kosten te verlagen en de prestaties in grootschalige web-API's met meerdere tenants te verbeteren.

GET https://api.contoso.com/tenants/adventureworks/orders/3

Gedistribueerde tracering en traceringscontext inschakelen in API's

Naarmate gedistribueerde systemen en microservicearchitecturen de standaard worden, neemt de complexiteit van moderne architecturen toe. Het gebruik van headers, zoals Correlation-ID, X-Request-IDof X-Trace-ID, om traceringscontext in API-aanvragen door te geven, is een best practice om end-to-end zichtbaarheid te bereiken. Met deze benadering kunt u aanvragen bijhouden terwijl ze van de client naar back-endservices stromen. Het vereenvoudigt snelle identificatie van fouten, bewaakt latentie en wijst API-afhankelijkheden toe aan services.

API's die ondersteuning bieden voor het opnemen van tracerings- en contextinformatie verbeteren hun waarneembaarheidsniveau en foutopsporingsmogelijkheden. Door gedistribueerde tracering in te schakelen, bieden deze API's een gedetailleerder inzicht in systeemgedrag en maken het gemakkelijker om problemen in complexe omgevingen met meerdere services bij te houden, te diagnosticeren en op te lossen.

GET https://api.contoso.com/orders/3
Correlation-ID: aaaa0000-bb11-2222-33cc-444444dddddd

HTTP/1.1 200 OK
...
Correlation-ID: aaaa0000-bb11-2222-33cc-444444dddddd

{...}

Web-API-volwassenheidsmodel

In 2008 stelde Leonard Richardson voor wat nu bekend staat als het Richardson Maturity Model (RMM) voor web-API's. De RMM definieert vier volwassenheidsniveaus voor web-API's en is gebaseerd op de principes van REST als architectuurbenadering voor het ontwerpen van webservices. Naarmate het volwassenheidsniveau toeneemt, wordt de API in RMM meer RESTful en volgt de principes van REST nauwkeuriger.

De niveaus zijn:

• Niveau 0: Definieer één URI en alle bewerkingen zijn POST-aanvragen voor deze URI. Simple Object Access Protocol-webservices zijn doorgaans op dit niveau.
• Niveau 1: Afzonderlijke URI's maken voor afzonderlijke resources. Dit niveau is nog niet RESTful, maar het begint in lijn te komen met HET RESTful-ontwerp.
• Niveau 2: Gebruik HTTP-methoden om bewerkingen op resources te definiëren. In de praktijk komen veel gepubliceerde web-API's ongeveer overeen met dit niveau.
• Niveau 3: Gebruik hypermedia (HATEOAS). Dit niveau is echt een RESTful-API, volgens de definitie van Fielding.

OpenAPI Initiative

Het OpenAPI Initiative is gemaakt door een brancheconsortium om REST API-beschrijvingen te standaardiseren voor alle leveranciers. De standaardisatiespecificatie werd Swagger genoemd voordat deze werd overgebracht onder het OpenAPI Initiative en hernoemd naar de OpenAPI-specificatie (OAS).

Mogelijk wilt u OpenAPI gebruiken voor uw RESTful-web-API's. Houd rekening met de volgende punten:

• De OAS wordt geleverd met een set adviesrichtlijnen voor REST API-ontwerp. De richtlijnen zijn voordelig voor interoperabiliteit, maar vereisen dat u ervoor zorgt dat uw ontwerp voldoet aan de specificaties.

• OpenAPI bevordert een contract-first benadering in plaats van een implementatie-eerste benadering. Contract-first betekent dat u eerst het API-contract (de interface) ontwerpt en vervolgens code schrijft waarmee het contract wordt geïmplementeerd.

• Hulpprogramma's zoals Swagger (OpenAPI) kunnen clientbibliotheken of documentatie genereren op basis van API-contracten. Zie ASP.NET Core-web-API-documentatie met Swagger/OpenAPI voor een voorbeeld.

Volgende stappen

• Zie gedetailleerde aanbevelingen voor het ontwerpen van REST API's in Azure.
• Bekijk een controlelijst met items die u moet overwegen wanneer u een web-API ontwerpt en implementeert.
• Bouw software als een service- en multitenant-oplossingsarchitecturen in Azure.