Hoe werkt de API?

Met de API kunt u alle benodigde handelingen uitvoeren om vanuit uw eigen applicatie de afspraken en klanten te beheren uit uw OnlineAfspraken.nl agenda. Dit doet u door middel van REST-aanvragen naar onze API-server. Een REST-aanvraag is een unieke URL met de benodigde parameters voor uw aanvraag. In de API referentie vindt u een overzicht van alle API-methodes en hun benodigde parameters. Iedere REST-aanvraag moet u ondertekenen middels een signing procedure welke u hieronder wordt uitgelegd. Op iedere REST-aanvraag wordt een XML-document geretourneerd met de response van de API-method.

Samengevat:

• Samenstellen API-call met de benodigde parameters
• Signen van de API-call
• Uitvoeren van API-call via REST-protocol
• Verwerken van response XML

Samenstellen van de parameters

Een REST-call heeft een aantal verplichte parameters, en een aantal al dan niet verplichte parameters welke voor iedere API-methode anders kunnen zijn. Een API-call bevat altijd:

Optioneel worden er per API-methode additionele parameters toegevoegd, in de vorm key/value.

Signen van de API-call

Om de request te signeren worden de gewenste API-functie en alle variabelen alfabetisch oplopend op key gesorteerd, en als key-value pairs zonder spaties achter elkaar geplakt. Daarna wordt de api_secret eraan geplakt, die evenals de api_key een vaste waarde is. Deze waarde is zowel bij de applicatie als bij de client bekend maar wordt nooit in een transactie meegestuurd. Hierna wordt de salt toegevoegd aan de te versleutel string. De salt is de huidige timestamp.

Voorbeeld

Om de API-call getResource te signeren waarbij we de resource met het id 8 willen ophalen wordt de te signeren string als volgt:

id8methodgetResourceAPISECRETSALT

( waarbij APISECRET en SALT vervangen worden door uw api_secret, en de huidige timestamp )

De api_signature is hierna een sha256-hash van deze string, dus:

$api_signature = sha256('id8methodgetResourceAPISECRETSALT');

Bestaande implementaties kunnen ook gebruik maken van sha1 om de handtekening te bepalen.

Uitvoeren van API-call via REST-protocol

Nadat de parameters voor deze API-call gesigneerd zijn met bovenstaande code kunt u de REST-call samenstellen. De REST-call voor het voorgenoemde voorbeeld is als volgt:

https://agenda.onlineafspraken.nl/APIREST?method=getResource&id=8&api_key=xx&api_signature=xx&api_salt=xx

Waarbij api_key uw eigen api_key is, api_signature de handtekening zoals verkregen via de sha256-hashing methode, en api_salt dezelfde timestamp is als waarmee de signature tot stand is gekomen. U verstuurt nooit uw api_secret!

Verwerken van response XML

Nadat u via een HTTP request de REST-call heeft uitgevoerd naar onze server ontvangt u een XML-bericht. Dit bericht bestaat altijd uit 2 delen:

Status

In de status vindt u in geval van een juiste API-call Status=Success, en bij een mislukte API-call Status=Failed, een foutmelding en meldcode. Daarnaast bevat het status segment altijd de datum van het bericht.

Voorbeeld juiste API-call:

<Response>
  <Status>
    <Status>success</Status>
    <Date>2011-07-07 12:34:56</Date>
  </Status>
  ...
</Response>

Voorbeeld mislukte API-call:

<Response>
  <Status>
    <Status>failed</Status>
    <Message>API required parameter id not found.</Message>
    <Code>B57</Code>
    <Date>2011-07-07 12:34:56</Date>
  </Status>
  ...
</Response>

Objects

In het objects-segment vindt u, in geval van een succesvolle API-call, één of meerdere objecten. Het object is per API-methode anders, zie hiervoor de API referentie voor de te verwachten objecten en de elementen die worden teruggezonden.

Voorbeeld agenda object:

<Response>
  ...
  <Objects>
    <Agenda>
      <Id>1</Id>
      <Name>Some calendar</Name>
      <DateFormat>yyyy-mm-dd</DateFormat>
      <TimeFormat>hh:mm:ss</TimeFormat>
      <AlignGrid>15</AlignGrid>
      <IsDefault>1</IsDefault>
    </Agenda>
  </Objects>
</Response>