Skip to content

Switching from API1

Jump to bottom
Alex Wyett edited this page Dec 19, 2018 · 2 revisions

API 2 is designed to be backwards compatible with API 1. In order to use the legacy (API1) routes of the API 2 you will need to replace the API URL that you are using currently (e.g. http://<brandcode>.api.carltonsoftware.co.uk/) with https://<agencycode>.api.tabs-software.co.uk/legacy/

Differences

HTTPS

HTTPS is now required to access the API. Failure to do so will result in a 400 error.

Content Type header

When posting to the /legacy routes you must set the Content-Type to be 'application/x-www-form-urlencoded'. Previously other values were accepted, even if they weren't valid.

Password endpoints

Access to the /owner/<ref>/password* endpoints poses a security risk, so now requires a new permission that is not available by default. In order to use these endpoints authorisation will need to be obtained from the agency.

Maximum page size

When getting a list of properties (/property), the pageSize parameter is limited to 1000. Attempting to fetch more than 1000 properties will return an error: "Maximum page size of 1000 reached".

Special Offers

Special offers have been extended significantly in tabs2. As such, a number of assumptions had to be made in order to display them within the legacy endpoints. Special offers will only be displayed if:

  1. The property branding is applied.
  2. If the special offer is active and advertised.
  3. If a special offer attribute is applied, the property must have a the same attribute and value.
  4. The special offer will not be output if it has a promotion.
  5. If all booking periods are in the past the special offer will be hidden.
  6. If all holiday periods are in the past the special offer will be hidden. If not, the fromDate and toDate will be the minimum fromDate and maximum toDate in the holiday periods collection.
  7. Website sections have been added to the legacy special offer (example below).
{
    "id": "1105_NO",
    "propertyRef": "1105",

    ...

    "specialOffers": [
        {
            "id": 16,
            "propRef": "1105",
            "fromDate": "2016-11-01",
            "toDate": "2026-07-31",
            "description": "Property-level description",
            "type": "P",
            "amount": 375,
            "websitesections": [
                {
                    "id": 1,
                    "section": "Property Pages"
                },
                {
                    "id": 3,
                    "section": "Last-minute Offers Page"
                }
            ]
        }
    ]
}

Allow Booking on Web

In tabs1 this is controlled by the AllowBookingOnWeb flag in the PropertyBrandYear table. In tabs2, we have an AllowBookingOnWebUntilDate field in the Branding and PropertyBranding tables. The value (if any) in the PropertyBranding table overrides the value in the Branding table, for any given property.

This is converted into boolean allowBookingOnWeb flags for 'this year' and 'next year' in the legacy/property endpoint response as follows:

  • if the property's current status does not allow booking (Status.allowbooking = false) then the allowBookingOnWeb booleans for 'this year' and 'next year' will both be false
  • otherwise, the allowBookingOnWeb boolean for 'this year' will be true if AllowBookingOnWebUntilDate is after December 31st of the current year, and for 'next year' if AllowBookingOnWebUntilDate is after December 31st of next year.

Rate Limiting

API 2 performs rate limiting, whereas API 1 doesn't. Once an application has reached it's assigned limit it will start receiving 429 errors until the limit has reset.

Limits are based on the APIKEY that is present within the query string of requests. Note that if the APIKEY is sent as a POST field on POST requests, a much stricter limit is applied. This stricter limit can be avoided by placing the APIKEY field in the query string on POST requests (this is what the API client that we provide does).

If you are using our api client, make sure you are using the latest version! Updates have been added in to the client which will handle any rate limiting caused by not adding the APIKEY parameter into the query string when doing PUT/POST requests.

Clone this wiki locally