Bookingsync

Developer API Documentation

Introduction

The BookingSync API is bringing you the basic Create, Read, Update, Delete (CRUD) actions.

It as been implemented as XML and JSON over HTTP using all four verbs (GET/POST/PUT/DELETE). Each resource, like Rental, Client or Booking, has its own URL and is manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as possible.

You can explore the view part of the API (everything that's fetched with GET) through a regular browser. Using Firefox for this is particularly nice as it has a good, simple XML renderer (unlike Safari which just strips the tags and dumps the content). Pretty much any URL in BookingSync can be viewed in its XML or JSON form by adding the .xml or .json extension. So /bookings/4 becomes /bookings/4.xml if you want to see the XML version or /bookings/4.json if you prefer to see the JSON version.

Authentication

When you're using the API, it's always through an existing user in BookingSync. There's no special API user. So when you use the API as "seb", you get to see and work with what "seb" is allowed to. Authenticating is done with an authentication token, which you'll find on the "Profile" screen in BookingSync.

When using the authentication token, you don't need a separate password. But since BookingSync uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it's often easier just to pass in a dummy password, like X.

Example using the authentication token and a dummy password through cURL
curl -u 123fb21s3:X https://www.bookingsync.com/bookings/1.xml

Remember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your email and password. If you come to fear that it has been compromised, just change your regular password and the authentication token will change too.

Reading through the API

The BookingSync API has two category of actions for reading: Show and List. Show returns a single record and list returns a collection. There's usually just a single show action for each resource, but many lists. All these actions are done through GET, which also means that they're all easily explorable through a browser as described above.

A few examples of reading with cURL
curl -u 123fb21s3:X https://www.bookingsync.com/rentals/1.xml
curl -u 123fb21s3:X https://www.bookingsync.com/bookings.xml

If the read is successful, you'll get an XML response back along with the status code "200 OK".

Writing through the API

Creating, updating, and deleting resources through the API is almost as easy as reading, but you can't explore it as easily through the browser. Regardless of your implementation language, though, using curl to play first is a great idea. It makes it very easy to explore the API and is perfect for small scripts too.

When you're creating and updating resources, you'll be sending XML into BookingSync. You need to let the system know that fact by adding the header "Content-type: application/xml", so we know that it's not regular form-encoded data coming in. Then you just include the XML of the resource in the body of your request.

Creating a new record

A few examples creating new resources, first with the XML inline, second referencing the XML from a file:

A few examples of creating records with cURL
curl -u 123fb21s3:X -H 'Content-Type: application/xml' \
-d '<rental><name>Anatoli</name></rental>' \
https://www.bookingsync.com/rentals.xml
curl -u 123fb21s3:X -H 'Content-Type: application/xml' \
-d @booking.xml https://www.bookingsync.com/bookings.xml

The response to a succesful creation is the status code "201 Created". You can get the URL of the new resource in the Location header (such that you know where to update your new resource in the future). We also include the complete XML for the final resource in the response. This is because you can usually get away with creating a new resource with less than all its regular attributes. Especially attributes like created_at can be helpful to get back from the creation.

Updating an existing record

Updating resources is done through the PUT verb and against the URL of the resource you want to update.

Example for updating a record with cURL
curl -u 123fb21s3:X -X PUT -H 'Content-Type: application/xml' \
-d '<rental><name>Villa Anatoli</name></rental>' https://www.bookingsync.com/rentals/2.xml
curl -u 123fb21s3:X -X -H 'Content-Type: application/xml' \
-d @booking.xml https://www.bookingsync.com/bookings/2.xml

The response to a successful update is "200 OK".

Deleting a record

Finally, you can delete resources (if you're allowed to) using the DELETE verb.

Example for deleting a record with cURL
curl -u 123fb21s3:X -X DELETE https://www.bookingsync.com/rentals/2.xml
curl -u 123fb21s3:X -X DELETE https://www.bookingsync.com/bookings/1.xml

Note that you don't need to pass the content-type header because you're not sending any XML. The response to a successful delete is "200 OK".

Handling failures

If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like:

Example of missing record failure with cURL
HTTP/1.1 404 Not Found
Date: Thu, 27 Oct 2009 13:37:23 GMT
...

Note that, in general, if a request causes a new record to be created (like a new client, or booking, etc.), the response will use the "201 Created" status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code.

SSL Note

Every request using the API must use SSL, simply make sure to use the HTTPS protocol at the start of your requests URL.

If forgotten, you will receive a "302 Found" redirection response. The Location header will contain the correct URL.

Alternative formats

XML is not the only other language than HTTP you can make BookingSync speak. We're also fairly fluent in JSON.

For JSON use the same calls as above and simply change the extension .xml for .json, this way you will retrieve a JSON formatted result.

Conventions in the API documentation

In the documentation that follows, the following notation is used:

  • #{text}: Indicates text that should be replaced by your own data
  • ...: Indicates content from the response has been elided for brevity in documentation.