REST API Overview

The REST API feature allows access to the database fields using a URL. This can be typed directly into a web browser or use in a program. Typically this feature might be used by:
  • web developers to augment your main marketing web site and pull data from theatre manager. This data could be used to show upcoming events (eg icons, text, dates, times, on sale status, etc)
  • selected employees to pull specific data or aggregated date for analysis
  • producers or other external companies that are enabled to see some data for their events.

The data can be delivered in a number of formats like plain text, (tab and comma delimited), JSON, EXCEL, HTML and some graphical formats.

Requirements for REST API access

In order to gain access to the rest API, the following requirements must be met :
  1. Theatre Manager 10.06.92 or later
  2. At least one web sales listener enabled in the Director.
    • The web listener is the process that responds to the API request.
    • Web sales are not required to be enabled to the outside world - but if you do online tickets sales, you need to be aware that extensive use may require additional web listener processes.
  3. The person needing REST API access must be set up as an employee in the database - this means only specified employees can have access.
    • and have the checkbox REST API: enable access via url on the employee access tab
    • the employee does not neccessarily have to be able to log into Theatre Manager desktop, but they:
      • must have an employee record
      • must not be resigned
      • can have any user level from 'no access' to 'normal access'
  4. Have created an account in the web store, which requires:
    • at least one email address associated with their patron account (multiple emails for an employee are ok)
    • and a password that allows them log into the web store
  5. A workstation, browser, or toolset that is capable of connecting using TLS 1.2 or later for security. If you can't connect, try latest firefox, chrome and/or on windows 10 or some smart phone.
  6. (optional) Consider requiring complex passwords via a setting in system preferences. online - which will also affect your regular patrons as well.

    Note: At this time, the web store password is probably different than the employee's Theatre Manager login account since they can set it themselves online.

    We recommend informing staff who are given access to the REST API to use complex passwords (or if you wish, make it mandatory). Since most people will not the API enabled for their employee account, they would be largely unaffected.

Logging in to the REST API

There are two likely ways you may wish to log into the REST API:
  • As a human using a browser or other program to view data. You will be prompted for a user id and password as per the help page.
  • From a program which submits requests and manages the data that returns. Current options are HTTP Basic Authentication or JWT

Logging in to the REST API From Browser

To begin using the API from a program or a browser, you need to start the login process. To do so send an https request that looks like:

https://tickets.yourvenue.org/api/v1

If you are inside your network, you can also type the URL of the TM server.. eg https://127.0.0.1/api/v1

The server will respond with a login screen where you provide:

  • The email address you use to log into the web site such as myemail@venue.org

    Note: if you have multiple logins in an outlet version of TM so there is ambiguity as to who you are, you may need to type your email address followed by:

    • ;outlet=xx such as myemail@venue.org;outlet=xx -and/or-
    • ;patron=yy such as myemail@venue.org;outlet=xx;patron=yy
  • the Password you use for online sales

    If you get your password wrong, you will see the login window again.

If you get your password correct, but are not enabled to use the API in your employee preferences, you will see a message similar to the one of the right that says API Access Disabled

You will need to enable API access to continue.

Successful access to API

If you see the window below showing a list of the top level end points, you have successfully accessed the API.

Logging in to the REST API As Programmer

Programmatically, there are currently two options to log into the REST api. You can use:
  • HTTP Basic Authentication The httpWatch web site describes the general process. Since it all occurs via SSL, this is quite secure
  • JSON web Tokens (JWT). Refer to the wikipedia description for more info.

REST API Top Level Endpoints

When you see the window below, you have successfully accessed the API. This shows a list of the endpoints -- which is a URL that:
  • will give you specific information that relates to the link. eg there is a patron end point that provides information about the patron and a ticket end point that focuses on ticket information
  • can be modified to only select specific columns
  • can have a sort order provided and data will return in that order
  • can have a query provided to only select data that you want
  • can also show some associated data (eg ticket date can show the patron, event and performance it is for

The end points are show in this manner so that they are discoverable. This means you can follow any one of them and see what kind of information it provides and can discover where it will lead.

 

Key columns in the top level endpoint list

Column Purpose
type This is one of
  • meta - which indicates that type of URL will describe something - i.e. meta data
  • data - the url will show actual data from the database
endpoint This is the endpoint name that can be added to the base url of the API to show the data. They are generally self describing and are case-sensitive.

For example, the endpoint carts will provide a list of shopping carts when added to the URL such as

https://127.0.0.1/api/v1/carts

data_url The data_url is provided so that you can easily click on the endpoint and see data from the database, if you are permitted to see that data within the Theatre Manger database as an employee. For the carts endpoint, the data_url is the same as above, i.e.

https://127.0.0.1/api/v1/carts

pages_url When the word pages is added to the data_url, the API will send the data back as pages of information with a default 25 lines of data per page. You can use next and previous to page through the data. For example

https://127.0.0.1/api/v1/carts/pages

You can navigate directly to a page of information by adding a ?page=x parameter (other parameters are discussed later). For example:

https://127.0.0.1/api/v1/carts/pages?page=2

schema_url If the word schema is added to the data_url, the API will provide a description of the columns in the particular endpoint. Using the carts endpoint as an example, the URL will be:

https://127.0.0.1/api/v1/carts/schema

Example of schema descriptions for Carts:

apps Shows the version of the applications supported by the current TM server

https://127.0.0.1/api/v1/apps

REST API accessig images

There is no specific API call to access images at this time. if you would like the images that are on web pages, please refer to Accessing Images

REST API Output Formats

The default output format for the REST API is in a human readable and navigable html format. That is not always the easiest for a web developer to deal with in a program, so the API offers a number of output formats that can be viewed using https://127.0.0.1/api/v1/extensions which produces a list like the one to the right.

 

Using one of the other output formats

It is very easy to use one of the other output formats. For example, to request that the output be in json format, simply add .json to the url.

After logging in to the REST API, try the following examples to get the sample page above in different formats:

This applies to all URL's in the REST API - using carts for example:

REST API Sorting data

The output from the REST API can be sorted by any field in ascending or descending order, whether you display it or not, by adding a sort= parameter to the api.

You can:

  • add multiple sort fields, separated by a '+' as long as the fields are recognized for the endpoint
  • sort in descending order by prefacing the field name with a '-'.

 

Examples of sorting data are:

REST API Qerying for Specific Results

There are multiple ways to search for data from the database. You can retrieve data using:

REST API Accessing a Specific Record using ID

If you know the record's ID number, you can retrieve it simply by adding /xxx after the endpoint. This retrieves data using the output format you've selected (the default is html).

 

Some examples of accessing a specific record are:

REST API Query Parameter

You can retrieve records using a query that contains one or more search terms by adding a single parameter q= to the api endpoint. Overall the syntax of the q= parameter is shown below and is explained afterwards. A query is:
  1. a condition which is a field name followed by a ':', followed by the search value, with or without quotes.
  2. multiple conditions can be used by putting a '+' between each of them
  3. single or double quotes are required if the value contains a space

 

Format

q=first_name:john+last_name:smith+-company:ibm

 

You can:
  • add multiple search conditions, separated by a '+' as long as the fields are recognized for the endpoint
  • where each each search condition is generally in the form field:value
  • negate any query by prefacing the field name with a '-'. Example a <= search, when negated, becomes >
  • put () around searches if you want to set the order of precedence. Example: (field1:value1+field2:value2)|(field3:value3+field4:value4)

 

Search Parameters by Variable Type

Conditions used in queries vary based on variable type. The following is a generalized list:

Variable Type parameter in URL Meaning
Numeric field:value field equals value (null can be used as value)
  field:>value field greater than value
  field:>=value field greater than or equal to value
  field:<value field less than value
  field:<=value field less than or equal to value
  field:value1..value2 field must be between value1 and value2
  field:[value1, value2, value3] field must be one of value1, value2 or value3
Character field:=value field equals value using case sensitive match (null can be used as value).

eg first_name:=Bob will find Bob, but not bob

  field:='value' field equals value using case sensitive match and where value can have spaces

eg first_name:='Bob and Betty' will find Bob and Betty, but not bob And Betty

  field:*value* field contains value where * is a wildcard that marches any characters (case insensitive) before and/or after value.

eg first_name:*bob* will find Bob, bob, bobby, and bebob

field:value field is like the value using case insensitive search

eg first_name:bob will find Bob, bob but not bobby

  field:'value' field is like the value using case insensitive search where value can have spaces

eg first_name:'bob 5' will find Bob 5, bob 5 but not bobby

  field:[value1, value2, value3] field is one of value1 or value2, or value3 (case insensitive).

eg first_name:[bob, ted, alice] will find bob, Bob, ted, tED, AliCe

  field:[value1*, value2*, value3] field is one of value1 or value2, or value3* (case insensitive and value3 starts with)

eg first_name:[bob, ted, ale*] will find bob, Bob, ted, alex, alecia, alexandra

  field:=[value1, value2, value3] field is one of value1 or value2, or value3 (case sensitive).

eg first_name:=[Bob, Ted, alice] will find Bob, Ted, Alice, bur not bob, ted or alice

  field:[value1, value2, value3] field is like one value1, value2, or value3 (case insensitive). This uses postgres 'ilike' comparator

eg first_name:[Bob, Ted, alice] will find Bob, Ted, Alice, bob, ted, alice, teddy, bobbie, boBBie, fested ...

  search:["value1", "value2"] does a postgres text search on the data in the endpoint.

eg search:["Bob", "art"] will find Bob, Bobbie, Art and Arts Management Systems (searches in all name and company fields").

Boolean field:value field equals, which is either true, false or null
Date field:value field equals value, value specifed in yyyy-mm-dd format, or null
  field:>value field greater than value in yyyy-mm-dd format
  field:>=value field greater than or equal to value in yyyy-mm-dd format
  field:<value field less than value in yyyy-mm-dd format
  field:<=value field less than or equal to value in yyyy-mm-dd format
  field:value1..value2 field must be between value1 (yyyy-mm-dd format) and value2 (yyyy-mm-dd format)
  field:[value1, value2, value3] field must be one of value1 (yyyy-mm-dd format), value2 (yyyy-mm-dd format) or value3 (yyyy-mm-dd format)

Packed Seq Fields/Packed Lists

These are special de-normalized lists of record connections. Examples of these fields are 'bought for plays', 'belongs to mail lists', 'associated with tags' where the specific record can be associated with multiple other records. A patron can belong to many mail lists. A play, donation campaign, or patron can be associated with many tags and searching for records with these markers can provide access to an arbitrary group of data, such as searching for all events with a tag.

Packed Lists field:[value1, value2, value3] field is one of value1, value2 or value3 where all values are internal record numbers that you would have found by some other means.

eg tag_ids:[5,6,7] will find all records with tag ids of 5, 6 or 7

  field:=[value1, value2, value3] field contains all seq #s of value1, value2 or value3 where all values are internal record numbers that you would have found by some other means.

eg tag_ids:=[5,6,7] will find all records marked with tag ids of 5, 6 and 7

 

Some Examples using the q= parameter are:

REST API Using Pagination

If you would like to see some data from an endpoint, you can use the page=XX parameter to specify which page of data you would like from the table. The contents of the page is affected by the any sort or other query parameters that you provide.

A quick way to see a sample of data is to use page=1. When you display a page, you will have next and previous on the html page so that you can navigate to next or previous pages easily.

There are some parameters that you can use to limit the amount of data:

  • page=XX - will show the XXth page of data, based on a default page size of 25 rows of data per page. For example, page=2 will show rows 26 to 50 data
  • page_size=YY - alters the page size from 25 rows of data per page to YY rows of data per page. It can be used in con with the page=XX parameter.
  • page_size=all - removes any page size limit for this query when displaying via html
  • split_size=ZZ -
  • page_size=all&stream=1 - is a very special combination of parameters that creates a continuous stream of all data and returns it from the API as fast as it can. Any program requesting data using this parameter needs be be able to parse the data in real time, as fast as it can because it could return a rather large set of data. It should not be used for viewing data.

 

Examples using pagination to limit results:

REST API Selecting Columns

You can select specific columns by adding only= to the parameter line. The names of the fields for the particular endpoint must be known and these can be determined by looking at the columns returned for a particular record or page of records.

Each column you want to see in your output is separated with a + (plus sign)

Examples:

REST API Adding Alias Names to Column

If you wish, you can rename the columns from the Theatre Manager standard names by adding an alias. This is done by adding a : and your alias name after specifying the column in the URL. You can use this feature if you want a different name when transporting the data to another service.

patron.id:patno renames patron.id to patno on output

Examples:

REST API Adding Relationships to Other Tables

The endpoints of the REST API specify a particular table from the database that you want to access. Some of those tables are related to other information - tickets are connected to the patrons that bought them, the event that it is for, and the performance time that the patron purchased. You can add in some fo that additional table connections by specifying them.

The starting place is finding what data is related to a particular endpoint using the related feature. The following shows:

Once you know which data is related, you can start to include that data onto the URL. In a one to many relationship, you normally start with the child or collection record.

Examples are:

REST API - showing relationships

If you just wish to show the other tales that are related to a specific table, you can show an endpoint (like orders or carts or patrons) and add /related to the url. eg:

https://127.0.0.1/api/v1/orders/related

Other Examples:

REST API summarizations, aggregations and groupings

You can summarize the data based on fields which requires a group= parameter followed by an agg= parameters indicating the fields you want to summarize by and how you want to summarize them. For example:

group=round(date_bought,1,month):purchase_date&agg=count+sum(total_cost)+avg(total_cost)

The group= allows you to summarize by text, number, boolean and date fields. You can also provide a function to summarize by parts of a date field.

Examples of the group= clause:

  • group=last_name - group patrons for summary by last name
  • group=company+last_name - group patrons for summarization by company and last name
  • group=date_bought - group the tickets by ticket the date they were bought - which may be of limited use as it contains time stamp
  • group=round(date_bought,1,month):purchase_date - group the tickets by date bought, but rounded to monthly increments. You can change a date grouping to be rounded to any interval, like 10 minute intervals

Examples of the agg= clause:

Query Breakdown:

Params are broken up by the ampersand &

  • Only sold tickets: q=-date_bought:null
  • Group by the purchase month: group=round(date_bought, 1, month)
  • Name it purchase_date
  • For each group aggregate the count of tickets, the total cost of tickets, and the average cost of each ticket: agg=count+sum(total_cost)+avg(total_cost)

Examples

REST API full syntax

The full syntax of the REST API for is shown below. This summarizes how to use it within Theatre Manager. The following conventions are used:
  • [ item ] - means that this part of the syntax is optional
  • [item, ....] - means that the item can be repeated
  • item1 | item2 - means you can use either Item1 or Item2 in the syntax

https://RestServerURL/api/v1 [/endpoint]

Putting it all together

the following examples show some of the power of the api to get exactly what you want.