Unitag Engine API

This document describes the HTTP interface for accessing the Unitag Engine API. This API allows to easily create and manage data-driven scenarios, called operations.

If you are displaying this page from GitHub, you are actually reading an API Blueprint specification. Although this format is readable as is, you may prefer switching to the enhanced version.

Base URL ¶

The following API routes are relative to this base URL:

https://betapi.unitag.io

This host name is voluntarily stamped as temporary, and will probably disappear after the beta stage (replaced by a nicer host name).

Authentication ¶

Every request to the Engine API must be authenticated using the following header:

Authorization: Unitag token="<your token>"

Beta tokens can be generated by Unitag upon request.

API reference ¶

The following HTTP methods allow to manipulate operations as JSON documents. The full format of an operation object is described in a separate document.

Examples ¶

Here is a minimal example, which simply redirects to Google:

{
    "url": "{YOUR PATH HERE}",
    "state": "PUBLISHED",
    "index": "http://www.google.com"
}

The following examples can also be used for learning and testing purposes:

• Hello World!: a simple Hello World!

• Tiny game: a more advanced example

• Echo: allows to display all available runtime data

• U.me: a simple HTML page

If you use the awesome Postman for API testing, you may want to import directly the request collection (remember to replace your authentication token).

Error handling ¶

When the Engine API encounters an error, it produces an HTTP response with an appropriate status code (4xx or 5xx) and a JSON body. This JSON document is always an object with the following keys:

• code: a string identifying the error

• message: a more verbose error description

• details: if present, additional data which could help to figure out the cause of the error

For example, an invalid resolver name will produce this kind of error:

{
    "code": "INVALID_RESOLVER_NAME",
    "message": "The resolver name is invalid. It must be a string containing alphanumeric characters, underscores, dashes, dots and/or tildes.",
    "details": {
        "path": "url[0].name",
        "data": {
            "expected": "UrlComponent",
            "markupAllowed": false
        }
    }
}

Like for most errors in the input document, the details object contains the following fields:

• path: indicates the JSON path at which the error occurred

• data: when present, provides some precisions about the circumstances of the error

What’s more, in order to avoid confusions, the API only returns keys that were actually used. Thus, even if unsupported keys are not rejected, this behavior can be used to determine whether a given key as been understood or ignored by the API.

Content-Type: application/json

{
  "id": "0123456789abcdef01234567",
  "creationTime": "1970-01-01T00:00:00.000Z",
  "url": [],
  "state": "PUBLISHED",
  "...": "..."
}

Content-Type: application/json

{
  "url": [],
  "state": "PUBLISHED",
  "...": "..."
}

Content-Type: application/json

{
  "id": "0123456789abcdef01234567",
  "creationTime": "1970-01-01T00:00:00.000Z",
  "url": [],
  "state": "PUBLISHED",
  "...": "..."
}

Content-Type: application/json

[
  {
    "id": "0123456789abcdef01234567",
    "creationTime": "1970-01-01T00:00:00.000Z",
    "url": [],
    "state": "PUBLISHED",
    "...": "..."
  },
  "..."
]

Content-Type: application/json

{
  "url": [],
  "state": "PUBLISHED",
  "...": "..."
}

Content-Type: application/json

{
  "id": "0123456789abcdef01234567",
  "creationTime": "1970-01-01T00:00:00.000Z",
  "url": [],
  "state": "PUBLISHED",
  "...": "..."
}