Using the API you can execute all required methods to manage appointments and customers for within your own application in your OnlineAfspraken.nl calendar. This is achieved by using REST-calls to our API server. A REST-call is a unique URL with the required parameters for your request. In our API reference you can find a summary of all our API-methods and their specific parameters required for their requests. Every REST-call should be signed using a singing procedure which is explained below. Every REST-request returns an XML-document with the response of the API-method.

In short:

• Creating the API-call with all required parameters
• Signing the API-call
• Executing the API-call via REST-protocol
• Parsing the response XML

Creating the API-call with all required parameters

A REST-call has a number of required parameters and a number of optional parameters which are different for each API method. Each API-call always requires:

Optionally you need to add additional parameters as key/value pairs, which differ per API-method.

Signing the API-call

To sign the request of a specific API method, alle parameters are sorted alphabetically by key, and concatenated as key-value pairs without whitespace. After that you concatenate your api_secret, followed by your api_key ( which is a fixed value ). The api_secret is known by our application as well as your client code, but is NEVER send in the request itself. Finally, the salt is added to the signature string. The salt is the current timestamp, and you should store the salt for now, because it is mandatory that the same salt is used for the siging of the string, AND is send in the REST request later.

Example

To sign the API-call getResource where we want to retrieve the resource with id 8, the string to sign is constructed as follows:

id8methodgetResourceAPISECRETSALT

( where APISECRET and SALT are replaced with your api_secret and the current timestamp )

The api_signature is the sha256-hash of this string, like:

$api_signature = sha256('id8methodgetResourceAPISECRETSALT');

For legacy reasons the signature may also be provided using sha1. New implementations however should always use sha-256.

Executing the API-call via REST-protocol

After the parameters for this API-call are signed using the code above you can construct the REST-call. The REST-call for the example above is:

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

Where api_key is your own api_key, api_signature is the signature as calculated using the sha256-hashing method explained earlier, and api_salt is the same timestamp as used for the hashing ( this is important to note! ). You NEVER send your api_secret!

Parsing the response XML

After you send a HTTP request with your REST-call you'lll receive and XML response message. This message always consists of 2 sections:

Status

In the status section you'll find for a succesfull API-call Status=Success, and for a failed API-call Status=Failed, an error messaeg and an error code. Additionally the status sections always contains the date of the message.

Example of succesful API-call:

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

Example of failed 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 the objects section, in case of a succesfull API-call, you'll find one or more object. This object is different for each API-methode, see the API reference for the objects to expect which elements are returned.

Example 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>