Unifii API

Status ¶

This document is in the draft state. It might not be complete and is subject to changes before the final release.

• To do:

  • Replace the HOST throughout the document with something other than dev.unifii.net.
  • Change the examples throughout the document to a more sensible project, maybe continuing the “feedback form” idea.

• Inconsistency in the API:

  • The RQL implementation doesn’t allow any way of specifying empty string or array values.

• Errors in content-interfaces.ts with respect to the observed results from API calls:

  • Interface Structure has rev required that doesn’t exist in the response from /structure
  • Interface Definition doesn’t match the response from /collections
  • Interface Compound doesn’t match the response from /collections/{identifier}
  • Interface Page doesn’t match the response from /pages and /pages/{identifier}

Background ¶

Forms in Unifii are represented by their definition document. This document specifies the fields and their order, and this information is used to render them. It may also contain validation rules, layout attributes and workflow states and actions.

Here’s a simple example of the definition of a form. This is a feedback form with three fields.

{
    "label": "Feedback",
    "identifier": "feedback",
    "bucket": "feedback",
    "fields": [
        {
            "type": "Text",
            "label": "Name",
            "identifier": "name"
        },
        {
            "type": "Choice",
            "label": "Feedback Type",
            "identifier": "feedbackType",
            "placeholder": "Please choose",
            "options": [
                {
                    "identifier": "Compliment",
                    "name": "Compliment"
                },
                {
                    "identifier": "Complaint",
                    "name": "Complaint"
                },
                {
                    "identifier": "Other",
                    "name": "Other"
                }
            ]
        },
        {
            "type": "MultiText",
            "label": "Message",
            "identifier": "message"
        }
    ]
}

Once completed, this form would produce a dictionary as follows:

{
    "name": "Bilbo",
    "feedbackType": "Other",
    "message": "Not all those who wander are lost"
}

The identifier of each field becomes a key in the dictionary and the user’s input becomes its value.

Bucket storage ¶

In order to facilitate rapid application development using Unifii forms, Unifii provides a schemaless document storage for data captured by the forms.

Storage is organised into buckets (equivalent to tables in the SQL world). The most common scenario is 1:1, where 1 form corresponds to 1 bucket. However, in certain situations, it may make a more sense to go with an N:1 setup, where the data from multiple forms are stored in 1 bucket.

In the example above, you can see that the Feedback form is associated with the feedback bucket.

Authentication ¶

The vast majority of the Unifii endpoints require authentication. Unauthenticated requests result in HTTP status code 401 Unauthorized.

The caller may be either a user or else an external system identified by an API Key.

User Authentication ¶

For user-based authentication, each request must send the user’s OAuth bearer token.

Authorization: Bearer {token}

API Key Authentication ¶

The authentication scheme for API Keys is based on message signing (HMAC-SHA256), using a shared secret. The client sends the API Key, and signs the request using the API Secret. Unifii verifies the request and the signature, upon receiving the request.

The API Key and the API Secret can be generated in Unifii Console under your project -> Settings -> API Keys -> Plus button. You need to have the ProjectManager role to access this functionality.

The HTTP header is defined like this:

Authorization: UNIFII {apiKey}:{signature}

Please see below how the signature is computed.

Unless otherwise noted, every request in this document needs to have this Authorization HTTP header.

Requests also need a timestamp header in the following format:

X-Unifii-Date: yyyy-MM-ddThh:mm:ssZ

The timestamp is verified by Unifii. All requests are valid for 10 minutes only.

The signature is defined as follows (pseudocode):

signature = base64(hmacSha256(stringToSign, apiSecret))

stringToSign =  {method} + '\n' + // GET, PUT, POST, DELETE, PATCH, ...
                {path} + '\n' + // URL path starting with a slash, e.g. /v1/projects/1/buckets -- use '/' for root
                {query} + '\n' + // query string without the question mark
                host:{host} + '\n' + // host header value, e.g. xxxxx.unifii.net
                content-type:{contentType} + '\n' // Content-Type header value -- use empty string if content-type will not be present
                accept-language:{lang} + '\n' // Accept-Language header value -- use empty string if the header is not present
                {date} + '\n' + // timestamp from X-Unifii-Date header

Example request:

GET https://xxxxx.unifii.net/v1/path?var=value%20with%20spaces HTTP/1.1
Connection: Keep-Alive
Accept-Encoding: gzip, deflate
Host: xxxxx.unifii.net

This would produce the following stringToSign. Note that there’s a new line at the end:

GET
/v1/path
var=value%20with%20spaces
host:xxxxx.unifii.net
content-type:
accept-language:
2017-06-30T00:27:58Z

The resulting signed request would be as follows in the Authorization header (using ApiKey for the API Key, followed by a colon and the signature):

GET https://xxxxx.unifii.net/v1/path?var=value%20with%20spaces HTTP/1.1
Connection: Keep-Alive
Accept-Encoding: gzip, deflate
Authorization: UNIFII ApiKey:RXAIGsnacjnC3HZwqON/OWtnyd6KW0ov7Itc+UgaQhc=
X-Unifii-Date: 2017-06-30T00:27:58Z
Host: xxxxx.unifii.net

Authorization ¶

Having been authenticated successfully, the user or API Key’s permissions will be checked for the request. Unauthorized access will result in HTTP status code 403 Forbidden.

These permissions are configured in Unifii Console under User Management -> Users or Roles -> Permissions. You need to have the UserManager role to access this functionality.

Errors ¶

The Unifii API returns standard HTTP response codes to indicate success or failure.

• Codes in the 2xx range indicate that an API request has succeeded.

• Codes in the 4xx range indicate that the request has failed due to a problem with the information provided. The request may be retried after correcting it according to the information that was returned in the response.

• Codes in the 5xx range are exceptional, indicating an error in the Unifii platform. The same request may succeed if retried, once the error has been rectified.

Preview versus Live API Calls ¶

In the documentation below, many of the APIs appear in pairs:

• The preview APIs have /preview in the URLs. They access content and forms that have been published for previewing or testing.

• The live APIs have simpler URLs. They access content and forms that have been published for production.

Although the preview and live data are completely separate, their behaviour is identical.

Query Parameters ¶

The Unifii API supports these capabilities by means of query parameters that may be appended to a call. The syntax for these parameters is a subset of Resource Query Language (RQL for short).

RQL consists of operators.

• Each operator has a name, e.g., eq for equals.

• The name is followed by a list of arguments in parentheses. Commas separate the arguments, e.g., eq(_state,Published).

  • Each argument may be a property, a value, an array, or another operator.
  • Use dot notation to refer to a nested property, e.g., eq(address.state,NSW).

• Operators can be nested, e.g., or(eq(_state,Draft),eq(_state,Published)). Nested operators constrain the surrounding operator.

Values are formatted as follows.

• Be sure to URL-encode all values.

• Do not use quotes around string values or dates and times.

• All times and dates are local (relative to the person filling out the form) unless they have a timezone offset, e.g., a suffix like +00:00 or Z. Please see RFC3339 for the format reference.

• An array is a set of items, surrounded by parentheses, e.g., in(_state,(Draft,Published)). Each item in the array can be a value or an operator.

• The data type of each value can be explicitly specified, e.g., eq(_definitionVersion,number:2)&eq(_state,string:Start)&eq(ready,bool:true).

Filtering ¶

The operators below can be used to filter results.

Sorting ¶

Only one property can be specified for sorting. If sorting is not specified, then the order of the results is undefined.

Pagination ¶

The results can be retrieved a “page” at a time. This can be much faster than retrieving all of the results in one call.

Combining queries ¶

There are some restrictions on how queries can be combined:

• = and & can only be used at the top level.

  • An illegal example would be or(a=b,eq(a,c)&ne(a,d)), because you cannot nest the shorthand operators inside other operators.

• sort and limit can only be used at the top level. Furthermore, they can only be combined with and or &, as in the example above.

  • An illegal example would be or(sort(+_lastModifedAt),limit(10,0)), because they would be ignored inside the or operator.
  • Only the first sort and limit are applied. Extra sort or limit operators would be ignored.

Your API Key may have conditional permissions defined for a bucket you’re accessing. These conditions will interact with your submitted query. Permission conditions impose an additional filter to ensure data isn’t leaked to unauthorized clients. For example:

• If a permission specifies a condition that restricts you to view only draft data;

• But your request is filtered for published data;

• Then, internally, the combined filter will be something like this:

  • and(eq(_state,Draft),eq(_state,Published))

The result of this combined filter would always be empty.

List Users ¶

This endpoint accepts RQL queries as defined above.

Get User by ID ¶

Gets user object based on its primary key.

Get User by Username ¶

Gets user object based on supplied username.

Bucket Transaction Log ¶

The transaction log records all form submissions (including previous revisions) in chronological order over time. It’s designed for efficient polling for synchronisation purposes. It allows clients to incrementally process or synchronise form data.

No restriction on poll frequency is enforced at the moment, however, Unifii reserves the right to change rate limits and their enforcement. Unifii’s recommendation is to poll once a minute at most. If your use case does not require immediate updates, please consider reducing polling frequency.

List all Buckets ¶

Lists the identifiers of all of the buckets in the given project.

Get a Bucket's Schema ¶

Retrieves the schema of a bucket. The schema shows the structure of the data contained within a bucket. The schema is derived from all of the forms associated with the bucket.

List some Data Items ¶

Lists some or all of the data contained in a bucket.

The data can be filtered, sorted and paginated to limit the amount of data retrieved by each call.

Get a Data Item ¶

Retrieves a single item of data contained in a bucket.

List all Revisions of a Data Item ¶

Retrieves all of the revisions of a data item within a bucket.

Get a Revision of a Data Item ¶

Retrieves a single revision of a data item within a bucket.

Get an Attachment ¶

Retrieves a file that is attached to some data.