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:

Let op: onze API ondersteunt meer case-specifieke features dan op deze publieke documentatie benoemt, waaronder een SSO oplossing. Neem contact op met support en vraag naar de mogelijkheden.

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:

api_key Uw persoonlijke API-key. U kunt uw API-key vinden in uw OnlineAfspraken.nl-backend, onder "Instellingen" -> "Extra functionaliteit" -> "API gegevens".
api_salt De huidige timestamp. De timestamp wordt ook gebruikt om de geldigheid van uw aanvraag te bepalen. Een URL is maximaal 5 minuten geldig. Het is hierom van belang dat het timestamp van uw server gelijk loopt met onze server. Dit is niet altijd het geval. In iedere response wordt de timestamp van onze server altijd meegestuurd zodat u altijd kunt bepalen wat het verschil is ten opzichte van uw server, en de salt hierop aanpassen. Onze server staat ingesteld op GMT +1, hetgeen gebruikelijk is voor een Nederlandse webserver. Op dit moment is de timestamp op onze server 1734788895. Uw salt moet dus altijd kleiner zijn dan deze waarde, maar maximaal 300 kleiner dan deze waarde.
api_signature Uw handtekening voor deze API-call
method De gewenste API-methode

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>