For Developers

Introduction

What is an API?

An application programming interface (API) is intended to be used as an interface by software components to communicate with each other.  Interacting with the API describes and prescribes the expected behavior of the software while the library is an actual implementation of this set of rules.

When used in the context of web development, an API is typically defined as a set of Hypertext Transfer Protocol (HTTP) request messages, along with a definition of the structure of response messages, which is usually in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format. While "Web API" is virtually a synonym for web service, the recent trend (so-called Web 2.0) has been moving away from Simple Object Access Protocol (SOAP) based services towards more direct Representational State Transfer (REST) style communications.

The practice of publishing APIs has allowed web communities to create an open architecture for sharing content and data between communities and applications. In this way, content that is created in one place can be dynamically posted and updated in multiple locations on the web.

How does this apply to tabs?

The tabs API provides a simple way for developers to make use of data contained within a tabs system, in a platform and language agnostic way.  This allows developers with no knowledge of the internal workings of tabs to develop websites, iPhone apps, or to provide data to affiliates easily, without having to worry about how prices are calculated, what extras should be added onto a booking, or whether a booking is allowed based on a property's short-break rules.

The tabs API is known as a RESTful (http://en.wikipedia.org/wiki/Representational_state_transfer) API.  What makes the REST API's easy to use is that they are built with the language of the internet, Hypertext Transfer Protocol (http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol), which means developers can make use of existing technologies to interact with the API, without having to reinvent the wheel themselves.

Potential Uses

There are many everyday applications which use REST API's, from providing data to websites to even sports cars (http://docs.timdorr.apiary.io/)! Although the tabs API won't be controlling any car headlights, here are a few examples of things you could do with the API.

  • Provide the cottage, booking and availability data needed to build your own website or mobile website
  • Build an iPhone/android app
  • Allow affiliates to access live availability and pricing
  • Allow affiliates to make bookings or enquiries from their own site
  • Automatically import your property data into your brochure creation software

Integration

The API is compatible with all major CMS systems such as Wordpress, Drupal, Perch and Joomla. It could also be integrated into an existing platform, it is simply, platform agnostic (http://en.wikipedia.org/wiki/Cross-platform).

Getting Started

Obtain an API key

In order to get started using the API you will first need an API key.  You will need to get the customer whom you are developing on behalf of to request an API key for you.  Please provide the following information along with your request:

  • Your name and contact details
  • Type of application being developed (website, iPhone app, etc.)
  • IP addresses of servers that will require access to the API

Take a look at the endpoints provided by the API

Details of each of the endpoints provided by the API is available on our documentation page (http://docs.carltonsoftware.apiary.io/).  For each endpoint you will find example URI's, status codes, headers and POST data (where relevant).

The API documentation also generates a mock-server, that you can send requests to from your application.  An example of using this mock-server is included in the next section.

Try some example requests

The following examples make use of the API dynamically generated from our documentation.

Requesting a property

Each resource contained within the API is identified by a URI (Uniform resource identifier).  To get the details of a resource, you simply send a GET HTTP request to the URI of that resource.  This can be done simply by opening up the URI in your web-browser of choice, for example:

Requesting a property - http://carltonsoftware.apiary.io/property/mousecott_SS. As you see in the browser when the page has loaded, the response is encoded in JSON (http://en.wikipedia.org/wiki/JSON) format. This is widely accepted format when using REST APIss and can be easily converted into useful data that websites or applications can use.

Whilst this is nice and simple, it isn't much use to an application. Below are a couple of examples of how to perform a simple HTTP GET request using some common tools.  You can also find some more examples, including how to send POSTs, PUTs and DELETEs in the examples (https://github.com/CarltonSoftware/api-documentation) folder.

Request (using the curl command line tool)

$ curl http://carltonsoftware.apiary.io/property/mousecott_SS

Request (using the PHP curl plugin)

<?php

//The URI to request
$uri = 'http://carltonsoftware.apiary.io/property/mousecott_SS';

//Create a new curl connection
$ch = curl_init();
// Set the URI that we want to request
curl_setopt($ch, CURLOPT_URL, $uri);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, '3');

//Perform the request, and assign the response to $response
$response = curl_exec($ch);

//Print out the response
print $response;

With both of these examples you’ll see a json response as shown here:

{
    "id": "mousecott_SS",
    "propertyRef": "mousecott",
    "brandCode": "SS",
    "url": "http://carltonsoftware.apiary.io/property/mousecott_SS",
    "accountingBrand": "SS",
    "slug": "mouse-cottage-southwold",
    "name": "Mouse Cottage",
    "address": {
            "addr1": "The Street",
            "addr2": "",
            "town": "Southwold",
            "county": "Suffolk",
            "postcode": "IP1 2AB",
            "country": "GB"
    },
    "coordinates": {
       "latitude": 52.2345,
       "longitude": 1.2345
    },
    "area": {
       "code": "COAST",
       "name": "Suffolk Coast"
    },
    "location": {
       "code": "SOUTH",
       "name": "Southwold"
    },
    "brands": {
        "SS": {
            "teaser": "Lorem (availability field)",
            "short": "Lorem",
            "description": "Lorem",
            "pricing": {
                "bookingBrand": "SS",
                "ranges": {
                    "2012": {
                        "high": 998,
                        "low": 325
                    },
                    "2013": {
                        "high": 1024,
                        "low": 275
                    }
                }
            }
        }
    },
    "accommodates": 10,
    "bedrooms": 4,
    "changeOverDay": "saturday",
    "shortBreak": true,
    "rating": 0,
    "pets": true,
    "promote": true,
    "attributes": {
        "washingMachine": true,
        "broadband": true,
        "distanceFromPub": 2
    },
    "images": [
        {
            "filename": "filename1.png",
            "url": "http://carltonsoftware.apiary.io/image/original/1x1/filename1.png",
            "alt": "Mouse Cottage - blue front door",
            "title": "Mouse Cottage",
            "width": "640",
            "height": "480"
        },
        {
            "filename": "filename2.png",
            "url": "http://carltonsoftware.apiary.io/image/original/1x1/filename2.png",
            "alt": "Mouse Cottage - courtyard garden",
            "title": "Mouse Cottage garden",
            "width": "480",
            "height": "640"
        }
    ],
    "specialOffers": [
         {
             "fromDate": "2012-06-09",
             "toDate": "2012-07-14",
             "description": "10% discount for full week stays between 9 June and 14 July 2012",
             "type": "%",
             "amount": 10
         },
         {
             "fromDate": "2012-07-14",
             "toDate": "2012-07-21",
             "description": "&pound;50 discount for full week stays between 14 July 2012 and 21 July 2012",
             "type": "&pound;",
             "amount": 50
         },
         {
             "fromDate": "2012-11-01",
             "toDate": "2012-11-30",
             "description": "10% discount for full week stays between 1 Nov and 30 Nov 2012",
             "type": "%",
             "amount": 10
         }
    ],
    "calendar": "http://carltonsoftware.apiary.io/property/mousecott_SS/calendar",
    "booking": "http://carltonsoftware.apiary.io/booking"
}

Using these methods, or clients, is not new and because the techniques involved are relatively mature, we would recommend using an existing client to use as a basis for performing your requests.  Clients like Guzzle (https://github.com/guzzle/guzzle), phphttpclient (http://phphttpclient.com/) or our own tabs-api-client (https://github.com/CarltonSoftware/tabs-api-client-example-docs).

Authentication

So far you will have been sending requests to the mock-server which doesn't require any authentication. When you start programming against the live API, you will be required to authenticate each request.  Instructions on how to do that can be seen here (https://github.com/CarltonSoftware/api-documentation/wiki/Authentication).