API Overview

All interactions with API are JSON based. Requests and responses are encoded as JSON messages sent and received via HTTP requests to particular endpoints, which may have additional GET parameters and path-based values. The particular JSON format that we use are based on a now obsolete version of the JSON-API standard, but it is fair to say that the format and conventions are intended to be simple and straightforward. All endpoint requests are made directly to the https://www.tallyfi.com base URI.

There are three main categories of api endpoint:

Entity endpoints: The Nouns of the system. Venues, Zones, Devices, Events etc.
Aggregate endpoints: Summaries and other calculated aggregates of Entity data.
Action/Utility endpoints: These tend to be the verbs of the system. They are point in time actions, or specialty requests. They map to functional-style RPC requests.

Entity Endpoints

The notable aspect of entity endpoints is that they contain type information. For example, when requesting information about a particular venue from the venue endpoint:

GET /api/1.0/venues/1 HTTP/1.1
apikey: 123456789

HTTP/1.1 200 OK
Content-Type: application/json

{
 "venue": {
     "id": 1,
     "name": "Test Venue",
     "capacity": 625,
     "zones": [
         2,
         3
     ],
 }
}

As shown above, this results a json response contains the key venue: indicating that the content is a single venue object in the corresponding value slot. The “zones” value within that object is also notable, as it denotes a relationship with another type, and it lists the ids for the zones that are related to the particular venue. Every entity is given an id value that unique within its type, and all references to other ‘types’ will refer to ID values.

Multiple Entity lookup

If we wanted to fetch the information on both these zones we can do a combined array lookup with a single request as follows:

GET /api/1.0/zones?ids[]=2&ids[]=3 HTTP/1.1
apikey: 123456789

Or if we just want an exhaustive list of all accessible zones:

GET /api/1.0/zones HTTP/1.1
apikey: 123456789

In both cases the result will be a response of type zones:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "zones": [
     {
         "id": 2,
         "capacity": 500,
         "name": "Zone 2",
         "devices": [
             1,
             2
         ],
         "venue": 1
     },
     {
         "id": 3,
         "capacity": 125,
         "name": "Zone 3",
         "devices": [],
         "venue": 1
     }
 ]
}

A look at the returned JSON shows that the parent object’s ‘type key’ returned indicates multiple zones are being returned (plural form) and the matched objects in list format.

Aggregate Endpoints

Aggregate endpoints are mostly the same as Entity endpoints. They combine the entity data together to formulate relevant statistics and are automatically updated as information is added to the system. The results are provided in a typed json object envelope, with the key being pluralized when the query warrants it.

Utility Endpoints

Utility endpoints are a straightforward way to request an action be taken or read a frequently updated aggregate value like the current count. The process is quite simple, and is customized to the needs of the endpoint - typically if the endpoint is idempotent, its parameters will be passed as part of the path. For instance, to request the current count for a venue:

GET /api/1.0/now/1 HTTP/1.1
apikey: 123456789

HTTP/1.1 200 OK
Content-Type: application/json;

{"maleTotal": 100, "femaleTotal": 50}

The precise details for each endpoint is provided in the Utility Endpoints chapter.