Skip to content

Dataviews API

Dataviews are customized datasets, defined by Yesplan users. A dataview can, for example, define a list of all events between start and end dates, together with all resource bookings on those events and list all pricing attributes as well as a selection of custom data elements.

The datasets defined by dataviews are best thought of as tables, which is their most common representation in the web app interface. However, dataviews are not limited to tabular datasets and can also represent hierarchical data structures.

For an API user, dataviews present a flexible alternative to the predefined HTTP API resources (endpoints), as each dataview assembles data that can be retrieved through a single API resource (endpoint).

Once a dataview is defined in Yesplan, its datasets can be retrieved via the HTTP API. We refer to these datasets as Dataview Results.

This document assumes you are familiar with the HTTP protocol as documented in RFC 2616, and with the Yesplan HTTP API.

Retrieving Dataview Results§

This section describes how to request and retrieve dataview results. Dataview results are always computed asynchronously: a request for a dataview result schedules its computation and Yesplan responds at which url the result can be retrieved when it’s ready. Once a computed dataview result is available, it will be cached for a duration relative to its computation time. During that timeframe, Yesplan will only respond the already cached result instead of computing a new one.

Request a Dataview Result Computation§

To request a new dataview result, you must perform a POST request to /api/dataviewresult/<dataview-id>/json/ where <dataview-id> is the id of the dataview. The id of the dataview can be retrieved from the application interface only. It can be found in the popover that is opened by clicking on the information icon next to the name of the dataview that is currently opened.

At this time, all dataview results are produced in JSON, but other formats are foreseen in the future. Therefore, it is required to include json in the path of all urls of the dataviews API.

The POST body should always contain a valid JSON object. If the dataview has parameters, the POST body should have a name/value pair for each parameter, where the name is the name of the parameter as shown in the application interface (case-sensitive). All possible JSON values are accepted, identical to elsewhere in the HTTP API. In addition, a Date can be formatted as a YYYY-MM-DD string. For example, the POST body below passes Date values for a dataview with parameters named “start” and “end”. If a dataview has no parameters, an empty JSON object (that is, {}) must still be passed.

{"start":"2017-01-01","end":"2018-01-01"}

Note that the parameters do not necessarily need to be primitive values, but can also be Yesplan objects such as Events, Profiles, Contacts, and so on. In these cases, the API expects these parameters to be JSON objects, in the format that is returned by the Yesplan HTTP API.

For example, consider the following parameter object that is passing a parameter named profile:

{
  "profile": {
    "url": "http://theater.yesplan.be/api/profile/8-1542349884",
    "_type": "profile",
    "id": "8-1542349884",
    "name": "project",
    "color": "rgb(34,34,34)"
    }
}

The profile object that is passed along to the dataview computation was in this case obtained by retrieving all the profiles via a GET request to /api/profiles.

A successful request will respond where the dataview result can be retrieved when it’s ready.

For example, to request a dataview result for a dataview with id 289503489-1510822734 and output format json, we make a POST request to https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json?api_key=5DCFB3CD88D5195D96FAC1DDCB1236CA with the aforementioned POST body. The response to a successful request will look like this:

{
    "contents": {
        "url": "https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/199122177",
        "status": "running",
        "creationtime": "2017-11-29T16:14:22.35488295555115+01:00",
        "id": "199122177",
        "dataviewid": "289503489-1510822734",
        "description": ""
    },
    "message": "Dataview result resource has been created"
}

The above response body will be returned for all identical requests for the same dataview result, until the result is ready. The status attribute with a value running indicates that the result is being computed (see below for all possible status values). When the computation finishes, the result will be available at the URL referenced by the url attribute. The response for a ready dataview result will look like this:

{
    "contents": {
        "numberofresults": 70386,
        "url": "https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/199122177",
        "cacheduntil": "2017-11-29T17:19:33.60808730125427+01:00",
        "creationtime": "2017-11-29T16:14:22.35488295555115+01:00",
        "description": "",
        "finishtime": "2017-11-29T16:25:14.23041701316833+01:00",
        "status": "success",
        "expirationtime": "2017-11-29T17:34:33.60808730125427+01:00",
        "id": "199122177",
        "dataviewid": "289503489-1510822734",
        "maxpagesize": 750,
        "computationduration": 651875.534057617
    },
    "message": "Dataview result resource is ready"
}

If you want to distinguish between responses that actually started the computation of a new dataview result, versus responses for already started and/or cached dataview results: a response that started the computation of a new dataview result will carry the http response status code 201, while a response for a cached result will use http status code 200.

Since it is undesirable to continuously request for a new dataview result to find out if the dataview result is ready, we provide a means to request the status of a dataview result, which yields the same response as shown above. This is described in the next section, where we also detail all attributes. It is also possible to receive a callback request when the dataview result is ready, this is described in further detail in the section “Receiving a Result Ready Callback Request”.

Retrieve Dataview Result Status§

The status of a dataview result can be requested using a GET request to /api/dataviewresult/<dataview-id>/json/<result-id>/status. The values for <dataview-id> and <result-id> must be identical to those used to request the dataview result. The value of <result-id> is the value of the id attribute that can be retrieved from the response of a succesful dataview result computation request.

Once it is scheduled, there are currently three possible states for a dataview result, indicated in the status attribute.

  • running: the dataview result is being computed, it is not yet ready.
  • success: the dataview result is ready for retrieval.
  • failed: an error occurred when computing the dataview result, see the description attribute of the status response object for more information.

Other attributes that are always present in the status response are:

  • url: the url where the dataview result can be retrieved.
  • creationtime: timestamp when the dataview result computation was started.
  • id: id of the dataview result.
  • dataviewid: id of the dataview.
  • description: more information in case of an error status.

An example status response for a dataview result that is being computed:

{
    "contents": {
        "url": "https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/335990017",
        "status": "running",
        "creationtime": "2017-12-06T09:18:32.48699498176575+01:00",
        "id": "335990017",
        "dataviewid": "289503489-1510822734",
        "description": ""
    },
    "message": "Dataview result resource is being computed"
}

Once a dataview result is ready, the status response also contains the following attributes:

  • numberofresults: the number of records in the result.
  • cacheduntil: timestamp until when this result will be used as a cached result for any subsequent identical dataview result requests.
  • finishtime: timestamp when the dataview result was ready.
  • expirationtime: timestamp until when this dataview result can be retrieved.
  • maxpagesize: maximum number of results that can be requests in paged requests.
  • computationduration: time it took to compute the dataview result, in milliseconds.

An example status response for a dataview result that is ready:

{
    "contents": {
        "numberofresults": 70386,
        "url": "https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/335990017",
        "cacheduntil": "2017-12-06T10:22:08.59428763389587+01:00",
        "creationtime": "2017-12-06T09:18:32.48699498176575+01:00",
        "description": "",
        "finishtime": "2017-12-06T09:29:08.5048770904541+01:00",
        "status": "success",
        "expirationtime": "2017-12-06T10:37:08.59428763389587+01:00",
        "id": "335990017",
        "dataviewid": "289503489-1510822734",
        "maxpagesize": 750,
        "computationduration": 636017.882108688
    },
    "message": "Dataview result resource is ready"
}

Receiving a Result Ready Callback Request§

When requesting a dataview result computation, it is possible to ask to receive a callback request when the result is ready. The callback request is sent as a HTTP POST request using a URL you pass in as part of the initial request. The URL is passed in through the header X-Notify-At. The following is an example dataview result computation request using the X-Notify-At header:

POST /api/dataviewresult/289503489-1510822734/json?api_key=5DCFB3CD88D5195D96FAC1DDCB1236CA HTTP/1.1
Host: theater.yesplan.be
Accept: */*
Content-type: application/json
Content-Length: 42
X-Notify-At: http://ticketing.system.com/yesplan-dataview-result-ready/123

{"start":"2017-01-01","end":"2018-01-01"}

The callback request is a POST request with, as its body, a JSON object with name/value pairs that give the “id”, “url” and “creationtime” of the dataview result. For the above example, that would be:

POST /yesplan-dataview-result-ready/123 HTTP/1.1
Host: ticketing.system.com
Accept: */*
Content-type: application/json
Content-Length: 189

{
    "id": "335990017",
    "dataviewid": "289503489-1510822734",
    "url": "https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/335990017",
    "creationtime": "2017-12-06T09:18:32.48699498176575+01:00"
}

After receiving the above callback request, the full status and data of the dataview result can be retrieved as described in, respectively, the previous and next sections. A callback request is sent when the dataview result is successfully computed, but also in the cases where the computation fails, or when a cached result is reused.

Any valid HTTP or HTTPS URL can be passed in for the X-Notify-At header. Note that URLs with other schemas are not allowed; this excludes, for example, ftp: URLs. The URL is used “as is”, except non-ASCII characters may be encoded differently in the callback request. At most one X-Notify-At header should be passed in with each dataview result computation request. A different URL can be used for each request, though this is not necessary.

A response should be given to the callback request. It is sufficient to simply respond with status code 200, without any body or headers. Note that responses with a status code other than 200 are simply ignored, including redirection status codes (3xx) and client error status codes (4xx). The callback request is sent once, and will not be retried if not responded to or responded to with status codes other than 200.

Retrieve Dataview Result§

A dataview result that was successfully computed can be retrieved entirely in a single request, or it can be retrieved in pages by specifying a start and end result number for each request.

To retrieve the entire dataview result at once, perform a GET request on the url you received when you requested the dataview result to be created. For example:

https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/335990017?api_key=5DCFB3CD88D5195D96FAC1DDCB1236CA

To retrieve the dataview result in pages, perform a GET request on the url you received when you requested the dataview result to be created and supply url query parameters from and to to specify the first and last result number of the page. For example:

https://theater.yesplan.be/api/dataviewresult/289503489-1510822734/json/335990017?from=1&to=500&api_key=5DCFB3CD88D5195D96FAC1DDCB1236CA

The first possible result number is 1 and the last is the value of the numberofresults attribute that can be found in the dataview result status response object. Mind that a request that exceeds the maximum page size will be rejected. The maximum page size is listed as the maxpagesize attribute of the dataview result status response object. This value can be different for each dataview result.

Caching and Expiration§

Dataview results that take a long time to compute are cached for a certain amount of time. During this caching period, no new dataview result can be requested: Yesplan will respond with the existing dataview result until the cache time expires. The end of the cache time is represented by the cacheduntil attribute in the status response of the dataview result, in the date-time format.

It is important to note that the data in a cached dataview result represents a snapshot of the system at the creation time of the dataview result. For example, if the dataview result contains a list of events, any changes made by Yesplan users to these events after the dataview result’s creation time are not included in the dataview result.

Each dataview result also has an expiration time, which always lasts longer than the cached time to ensure an API user has sufficient time to retrieve the entire dataview result. This is particularly important for dataview results that are computed quickly and therefore cached for only a very short time period. At this time, we have set the expiration time to a fixed 15 minutes after the cached time. The dataview status response includes this date-time in the expirationtime attribute.

A dataview result is automatically removed after the expiration time and can no longer be retrieved. A response with http status code 404 will be responded when trying to retrieve an already expired dataview result. At that time, an API user will want to request a new dataview result.

Dataview Result API Reference§

  • Request a new dataview result: POST /dataviewresult/<dataview-id>/json/ with body containing a JSON object with all required parameter values, e.g.:

    {
    'date': '2017-12-06',
    'number': 1,
    'string': 'name',
    'datetime': '2017-12-07T13:29:27+01:00',
}

  • Retrieve dataview result status: GET /dataviewresult/<dataview-id>/json/<result-id>/status

  • Retrieve a dataview result in one file: GET /dataviewresult/<dataview-id>/json/<result-id>

  • Retrieve a dataview result page: GET /dataviewresult/<dataview-id>/json/<result-id>?from=<start>&to=<end>