Dit hoofdstuk beschrijft het stapsgewijze proces van het onderhouden van gegevens in het gegevensmodel aan de hand van voorbeelden van verzoeken en reacties. In de verzoeken maken we gebruik van een fictief toegangstoken en een niet-bestaande domeinnaam. Vervang deze door de waarden die geschikt zijn voor jouw omgeving.

5.1 Data Model beschrijving

De structuur van het gegevensmodel kan rechtstreeks worden opgevraagd met behulp van de REST API. Een GET-verzoek met een 'format'-queryparameter die 'html' bevat en een geldige token zal een beschrijving van het gegevensmodel retourneren. Raadpleeg bijlage 6.2 voor de documentatie van het model dat in deze handleiding wordt gebruikt.

Dit document werd opgevraagd met de URL:

Voor de duidelijkheid zullen we in verdere voorbeelden het toegangstoken verkorten.

5.2. Simpele dataverzoeken

Als we ervan uitgaan dat we beginnen met een volledig leeg gegevensmodel, moeten we gegevens toevoegen voordat we verder kunnen gaan. Het invoegen gebeurt door POST-verzoeken te gebruiken. Eerst voegen we enkele pizza's toe aan het menu door een POST-verzoek naar de URL:

De body bestaat uit de volgende JSON:

Als dit verzoek succesvol is afgerond, zal de respons een X-Resource-header bevatten:

Let op het 'id' in de URL. We kunnen nu de gegevens uit het model ophalen met een GET-verzoek naar deze URL. We kunnen de 'format'-header weglaten, aangezien JSON de standaardindeling is, maar we moeten ons token toevoegen:

De respons bevat de informatie die we hebben verzonden en de metagegevens die door de API zijn toegevoegd:

Stel dat we de naam van deze pizza willen wijzigen. We zouden dezelfde URL gebruiken, maar in plaats van een GET-verzoek zouden we een PUT-verzoek gebruiken. In de body geven we de eigenschappen door die we willen wijzigen:

Als het verzoek correct is verwerkt, ontvangen we een andere respons met een 200-code en dezelfde resource-URL. Nog een GET-verzoek zal bevestigen dat de informatie daadwerkelijk is bijgewerkt:

Tenslotte, als we de resource willen verwijderen, kunnen we dezelfde URL opnieuw gebruiken, maar dit keer met een DELETE-verzoek. Dit verzoek zal geen gegevens of resource-headers retourneren. Het succes van het verzoek wordt aangegeven door de responscode. Om dit te bevestigen, kunnen we testen of de resource is verwijderd door nog een GET-verzoek naar de resource-URL te doen.

Dit zal een responscode 404 retourneren, met een aanvullende responsheader:

We kunnen ook een GET-verzoek doen zonder de id van de resource op te geven. De respons zal bestaan uit alle gegevens waarnaar de URL verwijst. Dit kan een zeer grote hoeveelheid gegevens opleveren en moet daarom met zorg worden gebruikt.

5.3. Complexe data verzoeken

De bovenstaande voorbeelden zijn voor een eenvoudige tabel, maar kunnen worden uitgebreid naar meer complexe situaties met gerelateerde tabellen. Als voorbeeld, laten we een bestelling invoegen. Als we ervan uitgaan dat er een klant in de Deployteq CRM is met id 42 en een reeks pizza's in ons gegevensmodel, kunnen we het volgende verzoek samenstellen:

In deze bestelling stellen we de eigenschappen van de bestelling zelf in en voegen we meteen twee pizza's toe aan de bestelling. Enkele belangrijke opmerkingen zijn van toepassing op het verzoek:

1. We kunnen verwijzen naar gegevens in de lookup-tabel die de pizza's zelf bevat door de waarde van het veld in de lookup-tabel. We hebben een lookup-relatie gemaakt tussen het veld 'pizza' in de 'orderedpizza'-tabel en het veld 'naam' in de 'pizza'-tabel. Door te verwijzen naar de pizza op naam in de bestelling, zal het gegevensmodel de juiste verwijzing creëren.

2. We kunnen elk veld dat we niet nodig hebben weglaten, zoals het opmerkingenveld in de tweede bestelde pizza. Het referentieveld voor de lookup-tabel kan ook worden weggelaten. Het verzoek zal slagen, en het record wordt ingevoegd, maar elke poging om de gerelateerde gegevens op te vragen, zal mislukken.

Als we een POST-verzoek doen naar de volgende URL:

wordt de order toegevoegd aan het klantrecord. Een GET-verzoek naar de teruggestuurde resource-URL bevestigt dit:

De verwijzingen naar de pizza's zijn resolved. Eigenlijk hadden we ook de IDs van de pizza's kunnen gebruiken bij het invoegen van de bestelling. Nu de bestelling een ID heeft die wordt geretourneerd in de X-Resource-header, kunnen we een 'orderedpizza'-record aan deze bestelling toevoegen door een POST-verzoek te doen naar de volgende URL:

met in de body van het verzoek enkel het orderedpizza record:

De geretourneerde X-Resource zal wijzen naar het ingevoegde 'orderedpizza'-record. Het bijwerken of verwijderen van de gegevens werkt zoals eerder gedemonstreerd. Bijvoorbeeld, het bijwerken van het aantal voor een van de bestelde pizza's kan worden gedaan door de bestelde pizza in de URL aan te spreken:

en het bijwerken van de eigenschappen door de volgende gegevens te gebruiken in een PUT-verzoek:

Het verwijderen van deze bestelling kan worden gedaan door dezelfde URL te gebruiken en een DELETE-verzoek te verzenden.

5.4. Beperken van geselecteerde gegevens

Bij een GET-verzoek kan de totale set teruggegeven informatie erg groot worden. Daarom is het mogelijk om de velden te specificeren waartoe een GET-verzoek beperkt moet worden, door een of meerdere 'fields[]' parameters in de queryreeks te gebruiken. Bijvoorbeeld, door de volgende URL te gebruiken:

zal een lijst van alle bestelde pizza's van alle klanten retourneren, inclusief opmerkingen. Omdat de 'clang_id'-velden niet zijn geselecteerd, is de volledige dataset geanonimiseerd. Als er geen 'fields[]' parameters aanwezig zijn in de queryreeks, worden alle velden teruggegeven.

Het is ook mogelijk om je resultaten te filteren met behulp van de 'filter[]' parameters in je URL. Bijvoorbeeld, als je alle bestellingen voor een specifieke datum wilt ophalen, kan dit GET-verzoek worden uitgevoerd met behulp van de volgende URL:

Als je in dit verzoek slechts een specifiek veld wilt laten terugtsuren, kun je de 'filter[]' combineren met de 'field[]' parameter.