Seats.io

The seatsio Developer Hub

Welcome to the seatsio developer hub. You'll find comprehensive guides and documentation to help you start working with seatsio as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

V2 Migration Guide

Introduction

This guide will help you migrate from API v1 to the new v2.

Since 1 March 2018 the v1 API is deprecated and will be shut down by the end of October 2018. It is important that you migrate to v2 before then, so that your application continues to work.

There's a new API version, aptly named v2, which is publicly available since 1 March 2018.

If you are new to seats.io, or just starting the integration, we recommend you to use v2 directly and avoid calling v1 endpoints.

Timeline

  • Feb 2017: When we started porting the API.
    To avoid a big bang release, we've been gradually migrating all API endpoints one by one. That's right: the v2 code has been running in production, some of it for over a year.
    If you're interested in a more detailed explanation, please refer to this blog post.

  • 15 Dec 2017: the day on which v2 was feature complete. Since then, all of the API calls to v1 were proxied to the v2 instance running in production.

  • 1 March 2018: v2 is publicly available. This is the start of the migration window.

  • 31 Oct 2018: v1 is switched off. This is the date by which you should have migrated your code to use the new API calls. We kept the migration window extremely large, so that you can choose the best moment to make the switch.

Why a new version of the seats.io REST API?

For a whole number of reasons, both functional and technical. In summary, we wanted and needed to consolidate the insights we've gathered, and to pay off some of the technical debt we'd been accumulating over the past few years.

The result is a cleaner, better, faster, nicer-to-use API.

We've dedicated a whole blog post to this question, which you can read here.

Changes - Overview

Here is an overview of the biggest changes between V1 and V2:

  • the base URL changed from https://app.seats.io/api to https://api.seatsio.net

  • the secret key is sent in a basic authentication header instead of being part of the URL (docs)

  • the calls to list charts, events and subaccounts are paginated (docs)

  • we've removed support for UUIDs when booking or releasing seats. Apart from the fact they were not UUIDs anyway, they did add an unnecessary layer of complexity, and frequently led to inconsistencies and hard-to-explain situations.

  • response compression behaviour is consistent across the API: payloads are uncompressed by default, but can be gzipped if requested (docs).

  • we've renamed '(temporary) reservations' to 'holds'. The term reservation regularily caused confusion, because it can mean many different things.
    Note that this is just a terminology change: functionally, a hold is exactly the same as a reservation, and a holdToken is exactly the same as a reservationToken.

  • we've created API client libraries for PHP, Java, C# and Python to make integration super-easy.
    Other languages to follow.

  • chart.js is now served through our CDN. Use https://cdn.seatsio.net/chart.js instead of https://app.seats.io/chart.js (or https://cdn.seats.io/chart.js) to avoid an unnecessary HTTP redirect.

Changes - Detailed

Below is an overview of each of the API endpoints v1 provides, and its the corresponding v2 counterpart.

Booking and releasing objects

Description
V1
V2

Book objects

POST
/book

Change general admission object status

Book objects for a whole season

Pass in extra data when booking

Temporarily reserving objects

Description
V1
V2

Temporarily reserve objects

Generate a reservation token

Change reservation token expiration date

POST
/hold-tokens/{token}

(note that it's a POST and not a PUT anymore)

Object entrances

Reporting

Users

Description
V1
V2

Create user (aka subaccount)

Charts

Events

Description
V1
V2

Create an event

POST
/events

Update an event

Create multiple events

Multiple calls to POST /events

Update multiple events

Multiple calls to POST /events/{eventKey}

chart.js