De Dynamics 365 Web API onder de knie krijgen met Postman

Wat is Postman?

Postman is het meest gebruikte API-platform ter wereld voor het ontwikkelen en testen van API's; volgens Postman zelf werken er meer dan 25 miljoen ontwikkelaars mee. Voor Dynamics 365-consultants en -ontwikkelaars is Postman een onmisbaar hulpmiddel om de Web API te verkennen, query's te testen, integratieproblemen te debuggen en API-aanroepen uit te proberen voordat u ze in code implementeert. Postman.

De Dynamics 365 Web API is een RESTful OData v4.0-endpoint dat programmatische toegang geeft tot de gegevens en metadata van uw organisatie. Met Postman kunt u snel query's testen, authenticatieflows valideren, de structuur van responses bekijken en problemen opsporen zonder één regel code te schrijven.

Waarom Postman gebruiken met Dynamics 365?

• Snel prototypen: Test API-query's en -bewerkingen voordat u ze in plugins of externe applicaties implementeert
• Authenticatie testen: Valideer OAuth-flows en los tokenproblemen op in een gecontroleerde omgeving
• API's verkennen: Ontdek beschikbare entiteiten, acties en functies via het $metadata-endpoint
• Integraties debuggen: Reproduceer en analyseer API-fouten die externe systemen melden
• Prestatieanalyse: Meet de responstijden van de API en spoor prestatieknelpunten op
• Documentatie: Maak en deel collecties als levende API-documentatie voor uw team

Aan de slag: installatie en configuratie

Postman installeren

Postman is beschikbaar als desktopapplicatie voor Windows, macOS en Linux. Er bestaat ook een webversie, maar de desktop-app presteert beter en werkt ook offline.

Installatiestappen:

1. Download Postman van postman.com/downloads
2. Installeer de applicatie en volg de instructies van het installatieprogramma
3. Maak een gratis Postman-account aan of log in met Google/GitHub
4. Maak een workspace aan voor uw Dynamics 365-projecten
5. Maak u vertrouwd met de interface: Collections, Requests, Environments

Authenticatie instellen met OAuth 2.0

De Dynamics 365 Web API vereist OAuth 2.0-authenticatie via Microsoft Entra ID (voorheen Azure Active Directory). De authenticatie correct instellen is cruciaal: zonder geldige authenticatie mislukt elk API-verzoek met een 401 Unauthorized-fout. Handleiding voor OAuth-authenticatie.

App-registratie in Microsoft Entra ID

Voordat u vanuit Postman kunt authenticeren, moet u een applicatie registreren in Microsoft Entra ID. Zo krijgt u de clientreferenties die nodig zijn voor OAuth-authenticatie.

Stappen voor de app-registratie:

1. Ga naar de Azure Portal (of het Microsoft Entra-beheercentrum) en selecteer "Microsoft Entra ID"
2. Klik op "App-registraties" → "Nieuwe registratie"
3. Naam: "Postman Dynamics 365 Web API" (of vergelijkbaar)
4. Ondersteunde accounttypen: "Alleen accounts in deze organisatiemap"
5. Omleidings-URI: Selecteer "Web" en voer in https://oauth.pstmn.io/v1/callback
6. Klik op "Registreren" en noteer de toepassings-id (client-id)
7. Ga naar "Certificaten en geheimen" → "Nieuw clientgeheim"
8. Voeg een beschrijving toe (bijv. "Postman-toegang") en stel de vervaldatum in
9. Kopieer de waarde van het geheim onmiddellijk (die wordt daarna niet meer getoond)
10. Ga naar "API-machtigingen" → "Een machtiging toevoegen"
11. Selecteer "Dynamics CRM" → "Gedelegeerde machtigingen"
12. Vink "user_impersonation" aan → "Machtigingen toevoegen"
13. Klik op "Beheerderstoestemming verlenen" als u beheerdersrechten heeft

OAuth 2.0 configureren in Postman

Zodra uw app in Microsoft Entra ID geregistreerd is, configureert u Postman om die referenties voor de authenticatie te gebruiken. De OAuth 2.0-implementatie van Postman haalt tokens automatisch op en vernieuwt ze ook.

Configuratiestappen:

1. Maak in Postman een nieuwe request of collection aan
2. Open het tabblad "Authorization"
3. Kies "OAuth 2.0" in de keuzelijst Type
4. Klik op "Get New Access Token" om de OAuth-instellingen te configureren
5. Vul de volgende velden in:
   • Token Name: "D365 Access Token"
   • Grant Type: "Authorization Code"
   • Callback URL: https://oauth.pstmn.io/v1/callback
   • Auth URL: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize
   • Access Token URL: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
   • Client ID: de Application (client) ID van uw app-registratie in Microsoft Entra ID
   • Client Secret: de geheime waarde die u eerder hebt gekopieerd
   • Scope: https://YOUR_ORG.crm.dynamics.com/.default
6. Klik op "Request Token": er opent een browservenster om aan te melden
7. Meld u aan met uw Dynamics 365-account
8. Klik na het aanmelden op "Use Token"

CRUD-bewerkingen met de Web API

De Dynamics 365 Web API ondersteunt de standaard RESTful CRUD-bewerkingen via HTTP-methoden: GET (ophalen), POST (aanmaken), PATCH (bijwerken) en DELETE (verwijderen). Wie met de API werkt, moet deze bewerkingen goed begrijpen. Documentatie over Web API-bewerkingen.

1. Create (POST)

Om records aan te maken stuurt u een POST-verzoek met een JSON-body die de gegevens van de entiteit bevat. De response bevat de URI van het nieuwe record in de OData-EntityId-header.

Voorbeeld: een account aanmaken

Content-Type: application/json
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
  "name": "Contoso Corporation",
  "telephone1": "+1-555-0123",
  "emailaddress1": "info@contoso.com",
  "address1_city": "Seattle",
  "address1_stateorprovince": "WA",
  "industrycode": 1,
  "revenue": 5000000
}

2. Retrieve (GET)

Met GET-verzoeken haalt u gegevens op uit Dynamics 365. U kunt afzonderlijke records of collecties ophalen, of queryopties gebruiken om de response te filteren, te sorteren en vorm te geven.

Voorbeeld: een account ophalen met $select en $expand

Veelgebruikte queryopties:

• $select: kies welke kolommen u terugkrijgt (beter voor de prestaties)
• $filter: pas filtervoorwaarden toe (bijv. revenue gt 1000000)
• $orderby: sorteer de resultaten (bijv. createdon desc)
• $top: beperk het aantal resultaten (bijv. $top=10)
• $expand: neem gerelateerde records op in de response
• $count: neem het totale aantal overeenkomende records op

3. Update (PATCH)

Met PATCH-verzoeken werkt u bestaande records bij. Neem alleen de velden op die u wilt wijzigen en laat ongewijzigde velden weg. Gebruik PATCH in plaats van PUT voor gedeeltelijke updates.

Voorbeeld: de omzet van een account bijwerken

{
  "revenue": 7500000,
  "description": "Updated after Q1 review"
}

4. Delete (DELETE)

Met DELETE-verzoeken verwijdert u records definitief uit Dynamics 365. Wees voorzichtig, zeker in productieomgevingen. Overweeg om records te deactiveren (statuswijziging) in plaats van ze te verwijderen, zodat de audittrail behouden blijft.

Voorbeeld: een account verwijderen

Geavanceerde bewerkingen

Batchverzoeken

Met batchverzoeken bundelt u meerdere bewerkingen in één HTTP-verzoek. Dat vermindert de netwerkoverhead aanzienlijk en verbetert de prestaties. Batchbewerkingen.

Structuur van een batch-request:

Content-Type: multipart/mixed;boundary=batch_AAA123
Accept: application/json

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json

{
  "name": "Account 1",
  "revenue": 100000
}

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json

{
  "name": "Account 2",
  "revenue": 200000
}

--batch_AAA123--

Best practices voor batchverzoeken:

• Beperk een batch tot 100 bewerkingen voor optimale prestaties
• Gebruik change sets voor transactionele bewerkingen (alles of niets)
• Combineer lees- en schrijfbewerkingen in dezelfde batch
• Vang gedeeltelijke fouten netjes op: batchresponses bevatten het resultaat van elke afzonderlijke bewerking
• Houd de API-limieten voor servicebeveiliging in het oog wanneer u batchbewerkingen gebruikt

FetchXML-query's

FetchXML is de eigen querytaal van Dynamics 365. Ze ondersteunt complexe query's, inclusief aggregaties, groeperingen en outer joins. FetchXML-referentie.

Voorbeeld: een FetchXML-query uitvoeren

Tips voor FetchXML:

• URL-encodeer FetchXML-query's wanneer u ze als queryparameter doorgeeft
• Gebruik FetchXML Builder in XrmToolBox om complexe queries visueel te ontwerpen
• Gebruik aggregatiefuncties (sum, avg, count, min, max) voor rapportering
• Gebruik link-entity voor joins tussen gerelateerde tabellen
• Voeg paginering toe aan grote resultatensets met de attributen page en count

Acties en functies

Dynamics 365 stelt bedrijfslogica beschikbaar via Actions (POST-bewerkingen met neveneffecten) en Functions (GET-bewerkingen zonder neveneffecten). Het gaat zowel om systeemacties (zoals WinOpportunity en QualifyLead) als om aangepaste acties die u zelf maakt.

Voorbeeld: de actie WinOpportunity aanroepen

{
  "OpportunityClose": {
    "subject": "Won the deal!",
    "opportunityid@odata.bind": "/opportunities(GUID)"
  },
  "Status": 3
}

Foutafhandeling en probleemoplossing

Wie API-problemen wil debuggen, moet foutresponses goed kunnen lezen. De Dynamics 365 Web API geeft gedetailleerde foutmeldingen terug in JSON-formaat, volgens de OData-conventies voor fouten.

Veelvoorkomende HTTP-statuscodes

• 200 OK: geslaagde GET- of PATCH-bewerking
• 201 Created: geslaagde POST-bewerking (nieuw record aangemaakt)
• 204 No Content: geslaagde DELETE- of PATCH-bewerking zonder retourwaarde
• 400 Bad Request: ongeldige syntaxis van het verzoek of validatiefouten
• 401 Unauthorized: authenticatie mislukt of token verlopen
• 403 Forbidden: onvoldoende rechten voor de bewerking
• 404 Not Found: entiteit of record bestaat niet
• 412 Precondition Failed: concurrencycontrole mislukt (het record is intussen gewijzigd)
• 429 Too Many Requests: API-limieten voor servicebeveiliging overschreden

Structuur van een foutantwoord

Bij een fout bevat de body van het antwoord gedetailleerde informatie over wat er misging:

{
  "error": {
    "code": "0x80040217",
    "message": "You do not have permission to access these records.",
    "innererror": {
      "message": "Principal user (Id=...) is missing prvReadAccount privilege",
      "type": "System.ServiceModel.FaultException",
      "stacktrace": "..."
    }
  }
}

Checklist voor debuggen

• Controleer of het OAuth-token geldig en niet verlopen is (kijk naar de vervaltijd van het token)
• Zorg dat de juiste headers meegestuurd worden (Content-Type, OData-MaxVersion, Prefer)
• Valideer de JSON-syntaxis van de request body met een JSON-validator
• Controleer of de logische namen van entiteiten en attributen exact overeenkomen (hoofdlettergevoelig)
• Ga na of de gebruiker voldoende rechten heeft voor de bewerking
• Bekijk de headers met de limieten voor servicebeveiliging (x-ms-ratelimit-*) in de responses
• Gebruik de Postman Console (View → Show Postman Console) om de ruwe requests en responses te bekijken

Best practices voor productiegebruik

Prestatie-optimalisatie

• Gebruik $select: Vraag altijd alleen de kolommen op die u nodig heeft: dat verkleint de payload en verbetert de prestaties
• Gebruik paginering: Gebruik $top en $skiptoken voor grote resultatensets in plaats van alle records in één keer op te halen
• Gebruik batchverzoeken: Bundel meerdere bewerkingen om de overhead van HTTP-verzoeken te beperken
• Cache metadata: Entiteitsdefinities, keuzelijsten en andere metadata veranderen zelden: cache ze aan de clientzijde
• Gebruik voorwaardelijke verzoeken: Gebruik If-Match-headers voor optimistische concurrencycontrole
• Beperk de diepte van $expand: Geneste expands drukken op de prestaties; haal gerelateerde gegevens zo nodig apart op

Beveiligingsoverwegingen

• Principe van minimale rechten: Gebruik serviceaccounts met alleen de machtigingen die strikt nodig zijn
• Referenties veilig opslaan: Codeer referenties nooit hard: gebruik Azure Key Vault of beveiligde omgevingsvariabelen
• Tokenbeheer: Vernieuw tokens tijdig, voordat ze verlopen (doorgaans na 1 uur)
• Invoervalidatie: Schoon alle gebruikersinvoer op om injectieaanvallen te voorkomen
• Alleen HTTPS: Gebruik altijd HTTPS voor API-communicatie (afgedwongen door Dynamics 365)
• Auditlogging: Schakel auditing in Dynamics 365 in om gegevenswijzigingen via de API te kunnen volgen

Testen en documentatie

• Maak collecties: Groepeer verwante verzoeken in Postman-collecties zodat u ze kunt hergebruiken
• Gebruik omgevingen: Maak omgevingsvariabelen voor DEV, TEST en PROD om gemakkelijk van context te wisselen
• Schrijf tests: Voeg Postman-testscripts toe om responses automatisch te valideren
• Genereer documentatie: Gebruik de documentatiefunctie van Postman om API-voorbeelden met het team te delen
• Exporteer collecties: Beheer uw Postman-collecties als JSON-bestanden in Git
• Monitor API's: Gebruik Postman Monitors om kritieke endpoints op vaste tijdstippen te controleren

Sjablonen voor Postman-collecties

Een goed georganiseerde Postman-collectie bespaart tijd en zorgt ervoor dat uw hele team API's op dezelfde manier aanspreekt.

Indeling van de collectie

• Authenticatie: Map met voorbeelden om tokens op te halen en te vernieuwen
• Metadata: Verzoeken om entiteiten, attributen en relaties te verkennen via $metadata
• CRUD-bewerkingen: Submappen per entiteit (Accounts, Contacts, Opportunities) met voorbeelden voor create/read/update/delete
• Query's: Voorbeelden van geavanceerd filteren, sorteren en FetchXML
• Acties en functies: Systeemacties (WinOpportunity, QualifyLead) en aangepaste acties
• Batchbewerkingen: Sjablonen voor batchverzoeken voor bulkbewerkingen
• Testen en diagnose: Endpoints voor health checks en query's voor probleemoplossing

Geavanceerde functies van Postman

Pre-request Scripts

Pre-request scripts worden uitgevoerd voordat een verzoek vertrekt. Zo kunt u dynamisch tijdstempels genereren, handtekeningen berekenen of controleren of een token verlopen is.

// Check if token exists and is not expired
const tokenExpiry = pm.environment.get("token_expiry");
const now = Date.now();

if (!tokenExpiry || now >= tokenExpiry) {
    // Token expired - get new token
    console.log("Token expired, requesting new token...");
    // Trigger OAuth flow or refresh token logic
}

Testscripts

Testscripts draaien nadat de response binnen is. Zo valideert u statuscodes, de structuur van de response en gegevenswaarden automatisch.

pm.test("Status code is 201 Created", function () {
    pm.response.to.have.status(201);
});

pm.test("Response has OData-EntityId header", function () {
    pm.response.to.have.header("OData-EntityId");
});

// Extract account ID from response
const entityId = pm.response.headers.get("OData-EntityId");
const accountId = entityId.match(/\(([^)]+)\)/)[1];
pm.environment.set("new_account_id", accountId);
console.log("Created account ID: " + accountId);

Collection Runner

De Collection Runner voert alle verzoeken in een collectie na elkaar uit, of volgens een eigen iteratielogica. Ideaal voor integratietests, het vullen van testdata of prestatietests.

• Voer volledige collecties uit om end-to-end workflows te valideren
• Gebruik databestanden (CSV, JSON) om verzoeken te parametriseren voor bulktests
• Genereer testrapporten om resultaten met stakeholders te delen
• Plan runs met Newman (de CLI van Postman) in CI/CD-pipelines

Postman in uw ontwikkelworkflow

Van Postman naar code

Codegeneratie is een van de waardevolste functies van Postman. Zodra een API-verzoek in Postman perfect werkt, genereert u er gelijkwaardige code voor in C#, JavaScript, Python of andere talen.

Stappen voor codegeneratie:

1. Maak en test uw verzoek in Postman tot het correct werkt
2. Klik op het codepictogram (</>) in het verzoekpaneel
3. Kies uw doeltaal of framework (C#, JavaScript, Python enz.)
4. Kopieer de gegenereerde code naar uw applicatie
5. Pas de code aan uw architectuur aan (foutafhandeling, retrylogica enz.)

Versiebeheer en samenwerken in team

Behandel uw Postman-collecties als code. Exporteer collecties en omgevingen als JSON-bestanden en commit ze naar uw repository voor versiebeheer en om ze met het team te delen.

• Exporteer collecties regelmatig en commit ze naar de Git-repository
• Gebruik Postman-workspaces om samen te werken en te delen in team
• Documenteer breaking changes in collectiebeschrijvingen
• Maak aparte branches voor experimentele API-wijzigingen
• Beoordeel wijzigingen aan collecties in pull requests, net als applicatiecode

Conclusie

Wie Postman goed beheerst voor de Dynamics 365 Web API, werkt als consultant of ontwikkelaar merkbaar sneller. Van het snel uitproberen van API-aanroepen tot uitgebreide integratietests: Postman biedt de tooling om efficiënt met de Web API te werken.

Begin met een correcte authenticatie, organiseer uw werk in goed gestructureerde collecties, gebruik omgevingsvariabelen voor flexibiliteit en neem geleidelijk geavanceerde functies zoals batchverzoeken en testscripts in gebruik.

Test altijd eerst in ontwikkelomgevingen, zorg voor degelijke foutafhandeling, respecteer de limieten voor servicebeveiliging en documenteer uw API-patronen zodat de kennis in het team gedeeld wordt. De tijd die u investeert in uitgebreide Postman-collecties, verdient zich gedurende de hele levenscyclus van het project terug.