Due to PCI compliant reasons we're going to turn off support for TLS v1.0 on all of our servers.
Please check/update you API implementations to support TLS v1.2 until 29.06.2018

REST API DataSync v2

From XING Events Developer Documentation
Jump to: navigation, search

This page contains information about the data synchronization API version 2. The version 1 of this API is now marked as deprecated.

Overview

Be aware, that the version 2 API has a different entry point domain, you will need to access it by https://api.xing-events.com/v2/...

The data synchronization API can be used to get updates about changes to your events and your participants. These updates include creates, updates and deletes.

The API is implemented as a synchronization API which means that you only get the updates which happened since you last called the API. This is achieved by keeping an ID which always gets incremented. An example:

After your last call to the synchronization API you have received "10" as your next ID.
Now you can periodically call:
GET /v2/sync/10

If there are new updates to be received you will for example get the following update:
GET /v2/sync/10 -> {"events":[{"id":27,"operation":"update", ...}],"nextId":28,"success":true}

Now you know that an object was updated (More details about the updates are below)
and that you should use the ID "28" for you next call to the API:
GET /v2/sync/28

NOTE: There are gaps in the IDs. This is intended.
If there are no updates, the answer will look like this:

GET /v2/sync/28 -> {"events":[],"nextId":28,"success":true}

So you will receive the same ID again if no updates have happened.

You can periodically call the API. It is written to be called quite often, for example, every 30 seconds.

To start using the sync you will need an apiKey (see How to get your API key) and register it to the sync API. Afterward you use the "normal" REST API to read the already existing data and afterwards start the sync requests.

Full example:

The first thing you need to do is register your API key with the sync api (once):
POST /v2/sync/register?apikey=<yourApiKey>

Read all the information you are interested in like event details and their existing participants.
See Event: Read, Events: Enumerate Participants,...

You do not have any sync ID yet, so you have to call it with a 1.
If nothing happened yet, you will get this:
GET /v2/sync/1?apikey=<yourApiKey> -> 
{
   "success":true,
   "events":[],
   "nextId":1
}

If for example someone bought a ticket a new participant update event will be returned:
{
   "success": true,
   "events": [
       {
           "id": 35,
           "path": "/api/participant/27",
           "objectType": "participant",
           "operation": "update",
           "objectId": 27
       }
   ],
   "nextId": 38
}

Properties

Attributes: R - accessible in read requests W - accessible in write (update) requests C - accessible in create requests

Property
Type
Attributes Description
id
Integer
R--
The internal id of this sync event.
operation
String
R--
The operation that was performed (update or delete). See below for details.
objectType String R--
The type of the object that changed (event, participant, etc.). See below for details.
objectId
Integer
R--
The id of the object that changed.
path
String
R--
The path for accessing the object that changes. See below for details.

Detailed description of the properties

operation

The operation property can hold the following values:

"update": 
An update operation is triggered if the referred object is created or a value of it has changed.
Use the REST API to read the new values of the object and update or create the item in your database.

"delete": A delete means that the referenced object is no longer available.
Note that you can not access the object in the REST API if it has been deleted.

objectType

The object type describes the object which is references. The following object types are available:

"event": 
Means that an event has changed, got created or deleted.

"ticketCategory": 
Means that a ticketCategory of an event has changed, got created or deleted.

"productDefinition": 
Means that the definition of an offered product of an event has changed, got created or deleted.

"participant": 
Means that a participant of an event has changed, got created or deleted.

objectId

The id of the object that has changed. An Example:

The objectType is "participant" and the objectId is 342.
Then you could access this object through: /api/participant/342

path

The path tells you where you can access the mentioned object. If you receive an "update" event, you can use the path to load the new values from XING Events.

The objectType is "participant" and the objectId is 342.
Then the value of path is the path to access this object: /api/participant/342

Methods

Register

Call POST /v2/sync/register
Parameters none, except your API key
Description You will need to call this method once with your API key to activate the SYNC process for the event(s) associated woth this key. Once the method is called every change in the events creates a sync object for this API key. Remember that this call will not create old sync events, you have to user the REST API to read the current status of the events and participants you are interested in.
Response {"success":true}.
Errors See General Errorcodes.

Read

Call GET /v2/sync/<id>
Description This request will return a list of sync events starting with the ID you provided. For your first call use the <id> 0. It will return a maximum of 200 sync events. In the next call of this function (where you update to the higher <id>) you will retrieve the remaining ones.
Parameters none, except your API key
Response {"success": true,"type": "dataSyncEventResult", "events": [{"id": 35,"path": "/api/participant/27","objectType": "participant","operation": "update","objectId": 27}],"nextId": 38} for a new update
{"success":true,"type": "dataSyncEventResult", "events":[],"nextId":38} if there are no updates
Errors See General Errorcodes.
REST API Contents
Getting Started Get your API key Overview Formats Errors
Data Types Event Participant Payment Ticket
Ticket Categories ProductDefinition Products CodeDefinition
TicketShop Addresses Ticket Types Payment Types
BankAccount UserDataDefinition UserData User
Partner ApiKey
Data Synchronization Sync Interface