TileInstance

TileInstance Service

Web service endpoints for Tiles.

It is possible to get a collection of tiles or an individual tile. You can also PUT to /tiles/{id}/data to push new data to a tile. However, note that tiles are not created via this endpoint. Refer to the Template Service for how to create tiles. It is done as a batch request by applying a template to a place.

Create Extended Properties

POST /tiles/{tileInstanceID}/extprops

Save a new set of extended properties for a tile instance with specified name/value pairs, and return an entity representing the newly created extended properties. Any previous extended properties for this tile instance will be completely replaced.

This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being created on the target tile instance will be those associated with the consumer of the oAuth token.

Path Parameters:
NameTypeRequiredDescription
tileInstanceIDStringtrueID of the tile instance for which to create a extended properties
Takes:
  • ExtProps describing the extended properties to be saved
  • Retrieves:
  • ExtProps representing the newly created extended props
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified instance cannot be found
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for external stream instance

    Create Extended Properties

    POST /tiles/{tileInstanceID}/extprops/addOn/{addonUUID}

    Save a new set of extended properties for a tile instance with specified name/value pairs, and return an entity representing the newly created extended properties. Any previous extended properties for this tile instance will be completely replaced.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance for which to create a extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are created.
    Takes:
  • ExtProps describing the extended properties to be saved
  • Retrieves:
  • ExtProps representing the newly created extended props
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified instance cannot be found
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for external stream instance
    Since: 3.9

    Create Private Properties

    POST /tiles/{tileInstanceID}/privateprops

    Save a new set of private properties for a tile instance with specified name/value pairs, and return an entity representing the newly created private properties. Private properties are scoped to the viewer and are not visible to nor do they overlap with any other user. Any previous private properties for this tile instance will be completely replaced.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being created on the target tile instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance for which to create a private properties
    Takes:
  • PrivateProps describing the private properties to be saved
  • Retrieves:
  • PrivateProps representing the newly created private props
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified tile instance cannot be found
    400 (Bad Request)An input field is malformed or max number of private properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for external stream instance
    Since: 3.10

    Destroy Extended Properties

    DELETE /tiles/{tileInstanceID}/extprops

    Delete the existing extended properties for the specified tile instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted from the target tile instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance for which the extended properties are to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified tile instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties

    Destroy Extended Properties For Addon

    DELETE /tiles/{tileInstanceID}/extprops/addOn/{addonUUID}

    Delete the existing extended properties for the specified tile instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance for which the extended properties are to be deleted
    addonUUIDStringtrueUUID of the addon for which the properties are deleted.
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified tile instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties
    Since: 3.9

    Destroy Private Properties

    DELETE /tiles/{tileInstanceID}/privateprops

    Delete the existing private properties for the specified tile instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted from the target tile instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance for which to create a private properties
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified tile instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties
    Since: 3.10

    Get Extended Properties

    GET /tiles/{tileInstanceID}/extprops

    Return the specified extended properties for the specified tile instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being fetched from the target tile instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance that is associated to the extended properties
    Retrieves:
  • ExtProps containing the specified extended properties
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)If the specified tile instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve these properties

    Get Extended Properties For Addon

    GET /tiles/{tileInstanceID}/extprops/addOn/{addonUUID}

    Return the specified extended properties for the specified tile instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance that is associated to the extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are fetched.
    Retrieves:
  • ExtProps containing the specified extended properties
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)If the specified tile instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve these properties
    Since: 3.9

    Get Instance

    GET /tiles/{tileInstanceID}

    Return the specified tile instance with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseID of the tile instance to be returned
    Retrieves:
  • TileInstance containing the specified instance
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified tile instance
    404 (Not Found)The specified tile instance does not exist

    Get Instance By External ID

    GET /tiles/external/{extensionUUID}/{externalID}

    Return the specified tile instance with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    extensionUUIDStringtrueThe UUID of the add-on in which the tile is defined
    externalIDStringtrueThe external ID of the tile instance to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseID of the tile instance to be returned
    Retrieves:
  • TileInstance containing the specified instance
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified tile instance
    404 (Not Found)The specified tile instance does not exist

    Get Instance Data

    GET /tiles/{tileInstanceID}/data

    Gets the data associated to the specified tile instance.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance you want to get the data from
    Retrieves:
  • 200 - JSON of the tile instance data.
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is missing or malformed
    404 (Not Found)The specified instance cannot be found
    410 (Gone)Tile instance is no longer available

    Get Instances

    GET /tiles

    Return a paginated list of tile instances that match the specified filter criteria.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    tilePage one Page URI ?filter=author(http://domain/api/core/v3/pages/1234)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this instance was created, in ascending order
    dateCreatedDesc Sort by the date this instance was created, in descending order. Default if none was specified.
    Query Parameters:
    NameTypeRequiredDescription
    sortStringfalseThe requested sort order
    startIndexIntegerfalseThe zero-relative index of the first matching instance to be returned
    countIntegerfalseThe maximum number of instances to be returned
    fieldsStringfalseThe fields to be returned on each instance
    Takes:
  • filters
  • Retrieves:
  • TileInstance[] of the matched tile instances
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed

    Get Private Properties

    GET /tiles/{tileInstanceID}/privateprops

    Return the private properties for the specified tile instance. Private properties are scoped to the viewer and are not visible to nor do they overlap with any other user.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being created on the target tile instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance for which to create a private properties
    Takes:
  • PrivateProps describing the private properties to be saved
  • Retrieves:
  • PrivateProps containing the specified private properties
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)If the specified tile instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve these properties
    Since: 3.10

    Update Instance Data

    PUT /tiles/{tileInstanceID}/data

    Sets the data and status associated to the specified tile instance. Only the remote system that provided the Tile or the admin of the place are allowed to push data into the tile instance.

    Path Parameters:
    NameTypeRequiredDescription
    tileInstanceIDStringtrueID of the tile instance you want to push data to
    Takes:
  • JSON object with an optional status field and an optional data field.
  • Retrieves:
  • 204 - No Content to indicate the operation was successful.
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is missing or malformed
    404 (Not Found)The specified instance cannot be found
    410 (Gone)Tile instance is no longer available
    403 (Forbidden)You are not allowed to perform this operation

    Update Instance Data By External ID

    PUT /tiles/external/{extensionUUID}/{externalID}/data

    Sets the data and status associated to the specified tile instance. Only the remote system that provided the Tile or the admin of the place are allowed to push data into the tile instance.

    Path Parameters:
    NameTypeRequiredDescription
    extensionUUIDStringtrueThe UUID of the add-on in which the tile is defined
    externalIDStringtrueThe external ID of the tile instance to be updated
    Query Parameters:
    NameTypeRequiredDescription
    access_tokenStringfalseThe oAuth access token of the tile instance to be updated
    Takes:
  • JSON object with an optional status field and an optional data field.
  • Retrieves:
  • 204 - No Content to indicate the operation was successful.
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is missing or malformed
    404 (Not Found)The specified instance cannot be found
    410 (Gone)Tile instance is no longer available
    403 (Forbidden)You are not allowed to perform this operation