Berichtindelingen voor aanvragen en antwoorden

Berichtindelingen voor aanvragen en antwoorden

De aanvraag

    <?xml version='1.0' encoding='UTF-8'?>
    <call method="exportData" callerName="a string that identifies your client application">
       <credentials login="sample@company.com" password="my_pwd"/>              
       method specific data goes here
    </call>

Deze regel geeft aan dat de volgende gegevens XML-gecodeerd zijn in UTF-8.
De tag <call> geeft aan welke API-methode wordt aangeroepen met behulp van het methodekenmerk. In dit voorbeeld is de API-methode exportData. Bovendien is callerName een vereist kenmerk in de <call>-tag. Het identificeert uw clienttoepassing voor het systeem en wordt gebruikt voor identificatiedoeleinden bij probleemoplossing en logboekregistratie.
Elke API-methode moet de gebruiker die de aanroep doet verifiëren. Dit wordt meestal gedaan door een aanmeldingsnaam en wachtwoord op te geven. Andere kenmerken kunnen hier worden opgegeven. Zie de documentatie voor elke API-functie voor meer informatie over referenties.
Voor sommige API-methoden zijn aanvullende gegevens in de aanvraag vereist. De methode exportData vereist bijvoorbeeld enkele criteria die beschrijven welke perioden, rekeningen, niveaus, enzovoort moeten worden gebruikt bij het ophalen van de gegevens. Dit gedeelte van de aanvraag verschilt van methode tot methode.
Dit is de sluittag voor de aanroeptag op regel 2.

Het antwoord

     <?xml version='1.0' encoding='UTF-8'?>
     <response success="true">
       <messages>
          <message key="modeled-import-success">Personnel import successful. Rows imported: 100</message>
       </messages>
       <output>
         ... method output ...
       </output>
     </response>

Net als de aanvraag geeft deze regel aan dat de volgende gegevens zijn opgemaakt als XML en zijn gecodeerd in UTF-8.
Elk antwoord is ingesloten in een <response>-tag. Als de aanvraag is geslaagd, wordt het succeskenmerk in de antwoordtag ingesteld op waar. Als de aanvraag is mislukt, wordt het kenmerk 'succes' ingesteld op 'false'.
Veel API-aanroepen retourneren dit optionele blok <messages> met een lijst met door de server gegenereerde berichten. Dit blok wordt mogelijk niet weergegeven als de server geen berichten had die moesten worden geretourneerd als antwoord op de aanroep. Foutberichten worden altijd in het berichtenblok weergegeven.
Elk bericht in het berichtenblok heeft een sleutelkenmerk dat aangeeft welk type bericht wordt verzonden. De berichttag bevat ook de tekst van het bericht van de server, inclusief retourwaarden, statuswaarden of andere zelfstandige metagegevens over het slagen of mislukken van de aanvraag. Een antwoord kan een onbeperkt aantal berichttags bevatten.
De afsluitende berichtentag.
De werkelijke uitvoer van de API-methodeaanroep, indien geretourneerd, wordt ingesloten in een <output>-tag.
De werkelijke uitvoer van de API-methodeaanroep wordt hier weergegeven. Deze uitvoer is afhankelijk van de methode die is aangeroepen.
De afsluitende uitvoertag.
De afsluitende antwoordtag.