Pitchup.com API

Introduction to the API

The Pitchup REST API allows access to bookings, availability and pricing from an external system.

A booking system can integrate with the API to provide access to bookings taken through the Pitchup system along with direct bookings to a site owner / operator. It can be used to automatically update pricing in line with a campsite's own pricing. It may also be used to adjust the amount of inventory allocated to Pitchup from the site's total inventory.

Rest API fundamentals

JSON

The recommended way of interacting with our API is through JSON requests. JSON is a simple, human readable, text based data interchange format. While JSON is quite simple there are a few rules which must be followed to ensure that the data is formatted correctly. Most programming environments will have a set of libraries for converting between its own standard data-types and JSON strings which will ensure the formatting is maintained correctly.

When manually formatting JSON care should be taken to ensure all of the properties are fully quoted strictly using double quotes and that those quotes have not been transformed into the unicode left and right double quotation marks.

There are a number of JSON format validators which can be used if an error is suspected, such as http://jsonlint.com/.

REST constructs

A RESTful API consists of a number of HTTP end points which represent the resources in a system. Some of the end points in the system will produce a list of resources, for example /rest/api/campsite/my-campsite/booking/ will list all of the bookings for "my-campsite". Others will detail a particular resource, for example /rest/api/campsite/my-campsite/pitchtype/123/.

The HTTP verbs GET / POST / PATCH / PUT are used in conjunction with these end points to view and manipulate the resources.

HTTP Verbs

GET

Used to retrieve resources from the API. For example /rest/api/campsite/my-campsite/booking/

POST

Used to create new resources within the API.

PUT

Used to modify a whole resource.

PATCH

Used to update only selected fields on a resource.

Links to other resources

Some resources will link to other resources. The campsite resource at /rest/api/campsite/my-campsite/ will contain links to the various pitchtype resources belonging to that campsite like https://www.pitchup.com/rest/api/campsite/my-campsite/pitchtype/123/.

It should be noted that the API implementation should follow these links whenever possible (caching where necessary) rather than permanently hard-coding them, or worse attempting to generate them through string concatenation. Doing so makes the implementation dependent on the structure of the API and should be avoided.

Pagination

Care should be taken to pay attention to the pagination of resources. It is easy to miss the fact that all resources can be paginated, especially as this may only come up with production volumes.

Pagination is indicated by the presence of the previous and next links on a list resource. As with resource links, these links should be followed rather than being manually generated.

{
    "count": 1023,
    "next": "https://www.pitchup.com/rest/api/campsite/my-campsite/booking/?page=2",
    "previous": null,
    "results": [
        ...
    ]
}

Filtering

Some end points support filtering as detailed below. The filters are simply added as a get request to the list end-point. For example https://www.pitchup.com/rest/api/campsite/my-campsite/booking/?after=2016-01-01&before=2016-02-01. If manually generating the get parameters by string operations care should be taken to make sure the question mark and ampersands are correctly placed.

Webhook

A webhook can be setup which will post the details of any new bookings in JSON format to a URL endpoint provided. The format is the same as the Booking resource below. There are some manual steps which are required to setup and test the webhook. Please contact your account manager if you require one to be setup.

Authentication

Finding authentication details

Authentication is acheived using an authentication token. This token can be found in the 'My details' section of the Pitchup manager portal.

My details API token section

Only 'API key (other booking systems)' can be used in conjunction with this API.

Using authentication details

This is passed to the API as an Authorization header. With curl this looks like the below:

curl -H 'Authorization: Token 7c33fec676104967958ab8ece0a1b76c' https://www.pitchup.com/rest/api/

Alternative authentication methods

As well as the token based authentication method it is possible to browse the API using the users logged in account. This is convenient during development where the credentials are available.

Authorization

A authenticated user will be able to see any of the campsites and linked resources which belong to that user account. They will not be able to see any resources relating to any other campsites or be able to assign them as linked resources.

Useful additions

Bulk updates

The ArrivalDay, AllocationDay and ExtraPrice end-points support adding multiple resources in the same request.

[
  {
    "date": "2016-08-15",
    "charge_type": "http://www.pitchup.com/rest/api/campsite/my-campsite/chargetype/4321/",
    "price": "17.51 GBP",
    "price_adult": "17.41 GBP",
    "price_child": "13.07 GBP",
    "price_infant": "09.05 GBP"
  },
  {
    "date": "2016-08-15",
    "charge_type": "http://www.pitchup.com/rest/api/campsite/my-campsite/chargetype/4321/",
    "price": "19.51 GBP",
    "price_adult": "17.41 GBP",
    "price_child": "13.07 GBP",
    "price_infant": "09.05 GBP"
  }
]

Upsert

The ArrivalDay, AllocationDay and ExtraPrice end-points also support an "upsert" type operation. Attempting to create one of these resources using the POST method will override the existing data (matching on the unique fields). This means there is no need to look up the detail view and PATCH each one individually.

Getting started

In order to start exploring the API it is useful to setup a test campsite in the sandbox environment. Starting at https://www.sandbox.pitchup.com/supplier2/signup/ the process is quite self explainitory. Alternatively, when developing an integration for an existing Pitchup.com client, it might be helpful to request their API key which can again be used directly in the sandbox. This has the advantage of having their site already setup with the correct pitchtypes.

Curl can be used to make requests to the API as follows.

> curl -H "Content-Type: application/json" -H  "Authorization: Token <TOKEN>" "https://www.sandbox.pitchup.com/rest/api/"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   559  100   559    0     0  15568      0 --:--:-- --:--:-- --:--:-- 15971
[
   {
      "campsite" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/",
      "arrival_days" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/arrival/",
      "extra_prices" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/extraprice/",
      "extras" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/extra/",
      "bookings" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/booking/",
      "allocation" : "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/allocation/"
   }
]

Note that the format of the two headers passed in are important and can lead to surprising errors if they are not used correctly.

If starting with a new test campsite it will be necessary to create at least one PitchType resource (which will atomatically create a matching default chargetype). This can be done by going to https://www.sandbox.pitchup.com/supplier2/ and selecting the "Pitch types and extras" tab. The "Add pitch pitch type" button on the right hand side will start the process.

Having created a PitchType and ChargeType using this form the browsable API will show the details at the relevant end points. Start at https://www.sandbox.pitchup.com/rest/api/campsite/ and note that you can now see the PitchType and ChargeType created using the supplier portal.

PitchType in browsable API

You can now begin adding allocation and rates for this PitchType - ChargeType combination. An easy way of getting started is to open the test campsite in the portal and use the Rates > Rates batch update form to create an Arrival Day. And the Allocation tab to add allocation to that date. You can then browse to the relevant sections in the API to use these elements as a template.

ArrivalDay in browsable API

Taking one of the Arrival Days from the results section and adding it to a file called arrival_day.json. We can make a few modifications and use it to change the price for this day.

$ cat arrival_day.json
{
    "charge_type": "https://www.sandbox.pitchup.com/rest/api/campsite/my_campsite/chargetype/33144/",
    "date": "2017-05-21",
    "price": "12.00 GBP",
    "price_adult": "6.00 GBP",
    "price_child": "5.00 GBP",
    "price_infant": "2.00 GBP",
    "min_days": 1,
    "pricing_period": 1
}
$ curl -H "Content-Type: application/json" -H  "Authorization: Token <Token>" -d @arrival_day.json "https://www.sandbox.pitchup.com/rest/api/campsite/my-campsite/arrival/"

A similar process can be followed to modify the allocation for one of the dates already setup, or indeed for any other date.