4.1 Basics
Het basisconcept achter REST (REpresentational State Transfer) is tweeledig:
- Een resource (bron) wordt uniek geïdentificeerd door een URL.
- Operaties worden geïmplementeerd als HTTP-verzoeken met behulp van een specifieke methode.
Door correct samengestelde verzoeken naar een specifieke URL te sturen met de juiste HTTP-verzoeksmethode, kunnen alle operaties die door de API worden aangeboden, worden uitgevoerd.
4.1.1 REST URLs
De basis URL voor de Deployteq Data Model REST API is:https://login.myclang.com/app/api
https://login.myclang.com/app/api/rest/public/v2/dataextension https://secure.myclang.com/app/api/rest/public/v2/dataextension |
|---|
De domeinnaam is afhankelijk van het portaal en het merk waarvoor je verzoeken wilt doen. Dus als je inlogt op https://login.myclang.com, gebruik je de eerste URL. Als je inlogt op je portaal op https://secure.myclang.com, gebruik je de tweede URL.
Het adresseren van resources in het gegevensmodel gebeurt door de resourcenaam en, indien nodig, de resourcenaam toe te voegen aan de URL. Bijvoorbeeld, de URL:
| https://.../dataextension/pizzas |
|---|
geeft toegang tot alle resources in de pizzatabel. In dit voorbeeld en alle onderstaande voorbeelden wordt de URL verkort weergegeven, maar uiteraard moeten alle verzoeken worden uitgevoerd met de volledige URL.
De URL:
| https://.../dataextension/pizzas/clang_523ae306ee3bf |
|---|
identificeert alleen de pizza met id clang_523ae306ee3bf in de pizzatabel. Alle resources in tabellen in het gegevensmodel ontvangen automatisch een id-veld met de naam clang_id met een unieke inhoud die wordt gegenereerd met het voorvoegsel 'clang_'.
Het is niet mogelijk om ids toe te wijzen via de API of op enige andere manier. Voor de klantentabel wordt een speciale id gebruikt. Klanten krijgen de Deployteq CRM-klant-id, voorafgegaan door 'clang_'. Als voorbeeld wordt het record voor de Deployteq-klant met klant-id 42 als volgt aangesproken:
| https://.../dataextension/customer/clang_42 |
|---|
Wanneer tabellen aan elkaar zijn gerelateerd met behulp van een "bevat" relatie, worden ze aangesproken als subresources binnen de resource die ze bevat.
Bijvoorbeeld:
| https://.../dataextension/customer/clang_42/order |
|---|
geeft toegang tot alle bestellingen van de klant met id 42.
| https://.../dataextension/customer/clang_42/order/clang_523ae3385d12c/orderedpizza |
|---|
Een stap dieper gaat naar alle pizza's in de bestelling met id clang_523ae3385d12c voor de klant met id 42. Wanneer een subresource wordt aangevraagd, moet de URL alle bevattende resources identificeren.
Het is bijvoorbeeld niet mogelijk om toegang te krijgen tot bestelgegevens zonder de klant op te geven. De volgende URL zal een foutmelding opleveren:
| https://.../dataextension/customer/order/ |
|---|
Belangrijk: de klantentabel is altijd gedefinieerd. Ongeacht de locatie waarin je werkt in Deployteq, herkent de REST API alleen de naam 'klant' (customer).
4.1.2. REST methodes
De REST API ondersteunt de volgende methoden. De resultaten van het verzoek kunnen variëren, afhankelijk van of je een id opgeeft in de resource-URL.
| HTTP method | withoud id | with id |
|---|---|---|
| GET | return all recources | return identified resource |
| POST | add new resource | invalid request |
| PUT | invalid request | update identified resource |
| DELETE | invalid request | delete identified resource |
4.2 REST responses
4.3.1 Response codes
De REST API reageert met de volgende reactiecodes:
| Code | Message | Meaning |
|---|---|---|
| 200 | Ok | The request completed succesfully |
| 304 | Not Modified | The request returns the same data as a previous GET request with the same properties |
| 400 | Bad request | The request is incorrectly formulated |
| 401 | Unauthorized | The request is not done with sufficient authorization |
| 403 | Forbidden | The request is not allowed access to the response |
| 404 | Not found | The requested resource is not present |
| 405 | Method not allowed | The requested operation is not allowed. |
| 410 | Gone | The requested resource is not present, and no alternative location is known. |
| 423 | Locked | The requested resource is present, but access to the resource is not possible at the time of the request. |
| 500 | Internal server error | An error occurred while processing the request. |
| 501 | Not implemented | The request method is not implemented in the API |
| 503 | Service unavailable | The REST interface is not accessible at the time of the request |
De precieze aard van fouten (codes in het 400-bereik) kan afhangen van het specifieke verzoek dat wordt ingediend.
4.3.2 Headers
REST-reacties bevatten de gebruikelijke HTTP-reactieheaders, en de REST-interface kan aangepaste headers toevoegen.
| Header | Content |
|---|---|
| X-Resource | The URL of the resource that was created or modified |
| X-Deployteq-API-Error | Additional information in case an error was returned |
Bij POST- en PUT-verzoeken wordt er geen gegevens in de respons geretourneerd. Als de ingevoegde of bijgewerkte gegevens vereist zijn, moet er een aanvullend GET-verzoek worden uitgevoerd naar de URL die wordt verstrekt in de X-Resource-header.
4.3.3 Body
Alleen in het geval van GET-verzoeken zal een REST-reactie gegevens bevatten in de responsbody, in de vorm van JSON. De gegevens die worden geretourneerd door de REST-interface zullen de informatie bevatten zoals beschreven in het gegevensmodel en metagegevens toevoegen die kunnen worden herkend aan de voorvoegsel 'clang_' bij de veldnamen.
De volgende metagegevens kunnen aanwezig zijn in de gegevens:
| Field | Value |
|---|---|
| clang_id | The id of the resource, which may be used in request URLs |
| clang_createdat | The timestamp of creation of the resource |
| clang_createdby | The Deployteq user that created the resource, often the user associated with the API token. |
| clang_modifiedat | The timestamp of the last modification of the resource. |
| clang_modifiedby | The Deployteq user that last modified the resource, often the user associated with the API token. |
Je kunt metagegevens niet instellen of wijzigen; deze worden automatisch door de API beheerd.