Generic Ticketing API

Summary

Yesplan provides a generic ticketing integration plugin. Any (ticketing) service that offers the HTTP API described in this document can be integrated with Yesplan.

The HTTP server is expected to provide REST-style collections of “events” and “productions”. The server should specifically provide HTTP resources at URLs with the following forms, and should be prepared to handle HTTP requests on these URLs with the listed HTTP methods:

HTTP Resource URLs	HTTP Methods
/events/{id}	GET, PUT, DELETE
/events?year={year}&month={month}	GET
/productions/{id}	PUT, DELETE
/mappings	GET

The process between Yesplan and ticketing

All events (shows, performances, concerts, etc.) are added in Yesplan by a programmer, depending on the kind of organisation this happens between now and 2 years ahead. All those new events are in ‘Option’, meaning that there are still some negotiations about pricing, deals, number of performances, dates, etc. going on.

Once an agreement is reached, the events will be set to ‘Confirmed’. From this moment on it is possible to send the event to the ticketing system so tickets can be sold. Some crucial information will be sent like the name of the event, starttime and endtime and the location. It is possible to add more data depending on the customers wishes (and our own), but this is limited. (It is not the goal to manage your whole ticketing with Yesplan too, Yesplan is no ticketing software).

Whenever something is changed to data which is linked, all linked data will be sent as an update immediately. Note: for the data that will be sent from Yesplan to ticketing, Yesplan is leading. This means the data should be changed in Yesplan. Of course, specific cases like the change of a location will be impossible when tickets are sold.

Once the ticketing is set up or the events are linked in the ticketing software, it is possible to retrieve some information about the ticket sales: capacity, the number of sold tickets, number reserved tickets, number free tickets, number of blocked seats, the return (income), etc. However, the data which is retrieved by Yesplan should be the same for each event.

Definition: Event, Production

An event is the show or performance on which tickets are sold. The calls specified below handling events are required.

Some ticketing software groups different events (shows) of the same production together at their side. For each of those events (shows) in that production tickets are sold. Yesplan can facilitate this concept of grouping with the productions call.

The use of production is not required. Also see Limited Implementations for more details.

Details

JSON Data Types

All data is exchanged using JSON. Yesplan identifiers and date-time values are exchanged as JSON strings that adhere to the following regular expressions:

• <id string>

  Regular expression: [1-9][0-9]*-(0|[1-9][0-9]*)

  Examples: 1102657025-0, 1563120641-1415099432, 3000401409-1512465626

• <date-time string>

  Regular expression: [1-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[0-9][0-9]\:[0-9][0-9]\:[0-9][0-9](\+|-)[0-9][0-9]\:[0-9][0-9]

  Examples: 2017-01-01T00:00:00+01:00, 2017-07-15T12:00:00+02:00, 2017-12-31T23:59:00+01:00

The format <date-time string> is based on the ISO 8601 standard. For values sent by Yesplan, the UTC offset is always the offset applicable for the time zone of the Yesplan installation at the represented point in time, taking into account summer and winter time. For customers in central Europe, these offsets are +02:00 for summer time and +01:00 for winter time. Thus, the example 2017-10-29T02:30:00+02:00 represents the first time the clock indicated 02:30 at the changeover from summer time to winter time in 2017, while 2017-10-29T02:30:00+01:00 represents the second time the clock indicated 02:30. For Yesplan installations of customers in the United Kingdom, the equivalent examples are 2017-10-29T01:30:00+01:00 and 2017-10-29T01:30:00+00:00.

The members of some JSON objects are not limited to a fixed set of names. The notation <custom name/value pairs> is used to indicate a JSON object can have additional members besides the ones listed. For objects sent by Yesplan, these members are defined by the customer, based on custom data fields. The format for the values is the same as used in the HTTP API, more details can be found in the section “Custom Data Reference” of the HTTP API documentation.

For JSON objects sent to Yesplan, there can be custom name/value pairs as well. The customer can set up custom data fields of type “Remote Data” into which the value of these pairs will be read. The values that can be read depend on the data type of the field:

Data type	JSON value
Single-Line Text	A JSON string, without any newline characters.
Multi-Line Text	A JSON string, newlines are allowed using the LF character (ASCII value: 10, JSON escape code: “\n”).
Number	A JSON number.
Date	A JSON string with the date in ISO 8601 format, for example "2013-12-01".
Time	A JSON string with the time in ISO 8601 format, for example "14:08".
Date and Time	A JSON string with the date and/or time in ISO 8601 format, for example "2013-12-01", "14:08" or "2013-12-01T14:08".
Single Option	A JSON string, limited to one of the possible values set for the field.
Multiple Options	A JSON array containing strings, where each string is one of the possible values set for the field.

Remark

For backwards compatibility, the JSON value for data type ‘Single-Line Text’ can also be a JSON number, while for data type ‘Number’ it can also be a JSON string containing a number. New implementations of the generic ticketing API should not rely on this behavior as it may be removed in the future.

Resources at URLs {…}/events/{id}

HTTP Method: PUT

Yesplan sends an HTTP PUT request to the configured url to publish or update an event. The body of the request is a JSON document as outlined below. A response code in the 2xx range lets Yesplan know that the event was correctly published. The response code can be 201 (“Created”) when the event has been created or 204 (“No Content”) when it has been updated. Yesplan doesn’t expect the response to include a body. Any response with status code outside of the 2xx range is considered as a publication failure.

Yesplan can send values defined in a Yesplan event’s custom data as custom-defined name/value pairs (indicated below with <custom name/value pairs>). The name of each pair can be determined in the Yesplan configuration settings and the value is identical to how the custom data field is exported by the Yesplan HTTP API.

Example URL: /api/events/{id}

The body (JSON) is a JSON object as follows:

{
    event-id: <id string>,
    production-id: <id string>,
    name: <string>,
    location: <string> (or <null>),
    starttime: <date-time string>,
    endtime: <date-time string>,
    <custom name/value pairs>
}

HTTP Method: GET

Yesplan triggers an HTTP GET request to the configured url to retrieve the (sales) data of a previously published event. The {id} is a required url parameter and Yesplan expects a response with code 200 and a JSON document as outlined below. Any response with status code outside of the 2xx range lets Yesplan know that an error occurred.

Yesplan expects the sales figures to appear in the <custom name/value pairs>. The value for the name ‘in-sale’ is expected to be true when the event is effectively in sale, meaning that there are useful values in the custom name/value pairs on sales figures. The value for the name ‘closed’ is expected to be true when the event’s provided data (from the ticketing service to Yesplan, i.e. sales figures) can no longer change.

mandatory url parameter: {id}

Example URL: /api/events/{id}

expected response body (JSON):

{
    production-id: <id string>,
    name: <string>,
    location: <string> (or <null>),
    starttime: <date-time string> (or <null>),
    endtime: <date-time string> (or <null>),
    in-sale: <boolean>,
    closed: <boolean>,
    <custom name/value pairs>
}

HTTP Method: DELETE

Yesplan triggers an HTTP DELETE request to the configured url to remove a previously published event. The {id} is a required url parameter. A response code of 204 lets Yesplan know that the event was correctly removed. Yesplan does not expect the response to include a body. Any response with a status code outside of the 2xx range is considered as a failure.

mandatory url parameter: {id}

Example URL: /api/events/{id}

Resources at URLs {…}/events?year={year}&month={month}

HTTP Method: GET

Yesplan triggers an HTTP GET request to the configured url to retrieve the (sales) data of a set of previously published events. The {year} and {month-number} parameters are required and Yesplan expects a response with code 200 and a JSON document as outlined below. Any response with status code outside of the 2xx range lets Yesplan know that an error occurred.

mandatory url parameters: {year},{month-number}

Example URL: /api/events?year={year}&month={month-number}

expected response body (JSON):

[
    {
        event-id: <id string>,
        production-id: <id string>,
        name: <string>,
        location: <string> (or <null>),
        starttime: <date-time string>,
        endtime: <date-time string>,
        in-sale: <boolean>,
        closed: <boolean>,
        <custom name/value pairs>
    }
]

Resources at URLs {…}/productions/{id}

HTTP Method: PUT

Yesplan triggers an HTTP PUT request to the configured url to create an (empty) production in the ticketing service, or to update a production. There are no URL parameters and the body is a JSON document outlined below. A response status code of 201 (“Created”) lets Yesplan know that the production was correctly created, while a response status code of 204 (“No Content”) lets Yesplan know that it was updated. Any response with status code outside of the 2xx range is considered as a publication failure.

A production is a group of events with a name. Each individual event references its production by id. This request is used by Yesplan to create a production (or to update its name) on the ticketing server.

Yesplan can send values defined in a Yesplan production’s custom data as custom-defined name/value pairs (indicated below with <custom name/value pairs>). The name of each pair can be determined in the Yesplan configuration settings and the value is identical to how the custom data field is exported by the Yesplan HTTP API.

Example URL: /api/productions/{id}

The request body (JSON) is an array of objects as follows:

{
    production-id: <id string>,
    name: <string>,
    <custom name/value pairs>
}

HTTP Method: DELETE

Yesplan triggers an HTTP DELETE request to the configured url to remove a previously created production. The {id} is a required url parameter. A response status code of 204 (“No Content”) lets Yesplan know that the event was correctly removed. Any response with status code outside of the 2xx range is considered as a failure.

mandatory url parameter: {id}

Example URL: /api/productions/{id}

Error Messages

Yesplan allows you to send custom messages when the response status is outside the 2xx range. You can do this by using a JSON object in the response body, with a single-line message (no line breaks):

{
    "displaymessage":
    "Sample error message given out by the ticketing system"
}

In the case of PUT requests, the message is shown as a tooltip when you hover over the publication status field:

If the ticketing system doesn’t send a message back, the tooltip shows a default message about the HTTP status code of the response:

Same value for event-id and production-id

It may occur that the value of the event-id and production-id are the same on the events calls.

{
    "event-id":"3432391937-1483009247",
    "production-id":"3432391937-1483009247",
    "name":"Test Event",
    "location":"Concert hall",
    "starttime":"2016-12-31T10:00:00+01:00",
    "endtime":"2016-12-31T12:00:00+01:00"
}

This is possible in 2 cases:

1. in Yesplan the event is not grouped in a production
2. productions are not supported by the ticketing software

Resource at URL /mappings

The ticketing system can provide a set of mappings to be used with dropdown custom data fields in Yesplan. Each mapping provides, on one hand, a list of options for a dropdown in Yesplan and, on the other hand, a corresponding value for each option that Yesplan should use in requests to the ticketing system. For example, a mapping can specify options “Large Concert Hall” and “Small Concert Studio” with corresponding API values “ID-4A5DB421” and “ID-BE8F73CA”. In Yesplan, a user will see “Large Concert Hall” and “Small Concert Studio” as the options in a dropdown custom data field, while Yesplan communicates the selected option to the ticketing system as respectively “ID-4A5DB421” or “ID-BE8F73CA”.

Yesplan will request the mappings through a GET request on the /mappings URL. The ticketing system should respond with status code 200 (“OK”), and a JSON body structured as in the following example:

{ "Venues": [
    { "option": "Large Concert Hall",
        "apivalue": "ID-4A5DB421" },
    { "option": "Small Concert Studio",
        "apivalue": "ID-BE8F73CA" } ],
    "Event Type": [
    { "option": "Pop Concert",
        "apivalue": "type_pop_concert" },
    { "option": "Piano Recital",
        "apivalue": "type_piano_recital" } ] }

The mappings are given as a JSON object with name/value pairs where the name is the name of each mapping. In the above example, two mappings are given: “Venues” and “Event Type”. For each mapping, the value of the name/value pair is a JSON array, consisting of JSON objects with name/value pairs for “option” and “apivalue”. The values for “option” and “apivalue” must be strings. The mapping “Event Type” in the example has two options, “Pop Concert” and “Piano Recital”, which are respectively mapped to “type_pop_concert” and “type_piano_recital”.

A few important points:

• The ticketing system is not required to provide any mappings: an empty JSON object ({ }) is a valid response to the request.
• A drop-down menu for which no value was selected will always result in an empty string value for that attribute (i.e. ""); this cannot be changed via a mapping definition.
• Configuring which attributes of an event (or production) use a mapping is left to Yesplan administrators; in other words, the ticketing system provides the mappings but does not determine where they are used.
• Yesplan only requests the mappings when a Yesplan administrator manually initiates an update of the mappings; this implies that Yesplan continues to use the same mappings when sending events and productions to the ticketing system until an administrator initiates an update of the mappings.
• If a drop-down menu contains values in Yesplan for which no mapping is defined, Yesplan will not be able to send a request and an error will be shown in the log of the integration, explaining for which value a mapping could not be found.

Limited Implementations

Servers are allowed to implement only a subset of the protocol:

• If the ticketing system does not allow deletions of events nor productions, the server may always respond with status code 405 to DELETE requests on /events/{id} and /productions/{id} URLs.
• If the ticketing system does not support productions, it does not need to store production data upon PUT requests on /productions/{id} as Yesplan conversely never retrieves production data (it never sends GET requests on /productions/{id}). The server should always respond 204 to DELETE requests on /productions/{id}.
• If the server does not allow retrieval of events data by month, the server may respond with status code 404 to GET requests on the /events?year={year}&month={month} URLs.

Authentication

Yesplan supports Basic Auth and OAuth 2.0.

Basic Auth

All requests include a header “Authorization” with the scheme “Basic”.

OAuth 2.0

The authorization follows the OAuth 2.0 protocol:

• Yesplan obtains an access token from the authorization server.
• All requests to the resources server then use the access token by including a header “Authorization” with the scheme “Bearer”.
• Yesplan currently only supports the “Password” grant type for obtaining the access token.

Tip

Read more about OAuth 2.0 and the “Password” Grant Type.