Skip to content

API.md

Latest commit

 

History

History
175 lines (124 loc) · 5.21 KB

API.md

File metadata and controls

175 lines (124 loc) · 5.21 KB

FORMAT: 1A HOST: https://betapi.unitag.io

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.

Group Operations API

Operation [/operations/{id}]

This resource represents one particular operation identified by its id.

  • Parameters

    • id (string) ... ID of the operation

  • Model (application/json)

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

Retrieve an operation [GET]

Retrieve an operation by its id.

Update an operation [PUT]

Update an operation.

  • Request (application/json)

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

  • Response 200

    Operation

Delete an operation [DELETE]

Delete an operation. Warning: this action permanently removes the operation from the database.

  • Response 204

Operations collection [/operations]

This resource represents the collection of created operations.

  • Model (application/json)

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

Retrieve all operations [GET]

Retrieve all the created operations.

Create a new operation [POST]

Create a new operation.

  • Request (application/json)

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

  • Response 201

    Operation