Annotation Service

The Aperture Tiles Annotation Service REST API is based on the Aperture Tiles Binning API. Annotations are submitted into tiles and aggregated through a given range of levels based on bin-index. Annotations can be written, modified and removed in real time.

Data Types

Annotation

A single annotation received from a GET request or submitted in a write, modify or remove POST request.

Method Detail

Parameters:
{Integer} level
Native zoom level in which the annotation is inserted.
{Real or Array of Real} x
Raw x data coordinate of the annotation. Either a Real or an Array containing two Real [min, max] for range-based annotations.
{Real or Array of Real} y
Raw y data coordinate of the annotation. Either a Real or an Array containing two Real [min, max] for range-based annotations.
{JSON} range
min and max key value pairs indicating the zoom-level aggregation range (inclusive). Given as Integers.
{String} group
Exclusive groupings by which annotations can be filtered.
{JSON} data
Additional information to be stored within the tile.
{JSON} certificate
Contains an RFC4122 version 4 compliant UUID and a Unix timestamp. Returned by the server upon successful write and modify operations.

Example:

{
    level: 6,
    x: 73.35,
    y: -125.6,
    range: {
        min: 0,
        max: 6
    }
    group: "Urgent",
    data: {
        comment:  ,
        author:  ,
        date:  
    },
    certificate: {  }
}

Annotation Tile

A collection of annotations from a single GET request. Contains all annotations (aggregated by bin-key) that pass through the current filter configuration.

Method Detail

Parameters:
{JSON} title
The respective tile index containing the level, x index and y index (where 0,0 is bottom left).
{JSON} annotations
An array of annotations aggregated by bin-key.

Example:

{
    index : {
        level: 7,
        xIndex: 8,
        yIndex: 4
    },
    tile : {
        values: [
            {
                value: [
                    level: 7,
                    x: 73.35,
                    y: -125.6,
                    range: {
                        min: 0,
                        max: 9
                    }
                    group: "Urgent",
                    data: {
                        comment:  ,
                        author:  ,
                        date:  
                    },
                    certificate: {  }
                ]
            }
        ]
    },
    version: "v1.0"
}

Annotation Certificate

An Annotation Certificate is comprised of the UUID and timestamp from a successful POST request. The certificate is used during remove and modify operations to ensure client-server coherency in the event of live editing conflicts. When a certificate in a supplied annotation does not match that held by the server, the request is ignored and an error status is returned to the client.

Method Detail

Parameters:
{String} uuid
An RFC 4122 Version 4 compliant UUID generated by the server.
{String} timestamp
A Unix timestamp generated by the server.

Example:

{
    uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    timestamp: "1401830862"

Web Services

Web service paths are relative to a common base URL. For example, assuming the hostname localhost and port 8080, the URLs of the various services would be:

  • https://localhost:8080/{version}/annotation/{layer}/{uuid}/{level}/{x}/{y}.{ext}
  • https://localhost:8080/annotation/{layer}/{level}/{x}/{y}.{ext}
  • https://localhost:8080/{version}/annotation
  • https://localhost:8080/annotation
  • https://localhost:8080/{version}/layer/{layer}
  • https://localhost:8080/layer/{layer}
  • https://localhost:8080/{version}/layer
  • https://localhost:8080/layer

Read Annotation Tile

Returns an Annotation Tile for a specified filter configuration UUID, annotation layer, level and tile x and y.

Method Summary

Attributes Description
URL
/{version}/annotation/{layerId}/{level}/{x}/{y}/{z}.{ext}
Method
`GET`
Output MIME Type
application/json
Output
Annotation Tile

Method Detail

URL Parameters:
layer
Annotation layer ID.
uuid
Filter configuration UUID. Submit default to use the default server filter configuration.
level
Zoom level, where 0 is highest level of aggregation.
x
Horizontal tile index, where 0 represents the leftmost column of tiles.
y
Vertical tile index, where 0 represents the bottommost row of tiles.
.ext
The extension of the annotation format. Only JSON is currently supported.

Example request:

GET http://localhost:8080/instagram/rest/v1.0/annotation/parlor-annotations/4/1/2/3.json

Example response:

{
    index : {
        level: 7,
        xIndex: 8,
        yIndex: 4
    },
    tile : {
        values: [
            {
                value: [
                    level: 7,
                    x: 73.35,
                    y: -125.6,
                    range: {
                        min: 0,
                        max: 9
                    }
                    group: "Urgent",
                    data: {
                        comment:  ,
                        author:  ,
                        date:  
                    },
                    certificate: {  }
                ]
            }
        ]
    },
    version: "v1.0"
}

Write Annotation

Submits a new annotation to be written to the server. Upon success, a certificate containing the UUID and timestamp is returned to the client.

Method Summary

Attributes Description
URL
/{version}/annotation/{layerId}/
Method
`POST`
Output MIME Type
application/json
Output
AnnotationCertificate

Method Detail

Request Parameter Description Data Type Single/Multiple Required?
type
"write"
String
Single
Yes
layer
annotation layer id
String
Single
Yes
annotation
annotation
JSON
Single
Yes

Example request:

POST http://localhost:8080/instagram/rest/v1.0/annotation/parlor-annotations/
{
    type: "write"
    layer: , "annotation-test-layer-id",
    annotation: {
        level: 6,
        x: 73.35,
        y: -125.6,
        range: {
            min: 0,
            max: 6
        }
        group: "Urgent",
        data: {
            comment:  ,
            author:  ,
            date:  
        }
    }
}

Example response:

{
    uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    timestamp: "1401830862",
    version: "v1.0"
}

Modify Annotation

Submits a modify request to the server. If the certificate in the annotation state is valid, the operation is processed and a new certificate is returned.

Method Summary

Attributes Description
URL
/{version}/annotation/{layerId}/
Method
`POST`
Output MIME Type
application/json
Output
AnnotationCertificate

Method Detail

Request Parameter Description Data Type Single/Multiple Required?
type
"modify"
String
Single
Yes
layer
annotation layer id
String
Single
Yes
current
The annotation after modification. Must contain a valid certificate key.
JSON
Single
Yes

Example request:

POST http://localhost:8080/instagram/rest/v1.0/annotation/parlor-annotations/
{
    type: "write"
    layer: , "annotation-test-layer-id",
    annotation : {
        level: 6,
        x: 73.35,
        y: -125.6,
        range: {
            min: 0,
            max: 6
        }
        group: "Urgent",
        data: {
            comment:  ,
            author:  ,
            date:  
        },
        certificate: {
            uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            timestamp: "1401830862"
        }      
    }
}

Example response:

{
    uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    timestamp: "1401830862",
    version: "v1.0"
}

Remove Annotation

Submits a removal request to the server. If the certificate is valid, the operation will be processed and a success status will be returned.

Method Summary

Attributes Description
URL
/{version}/annotation/{layerId}/
HTTP Method
`POST`
Output MIME Type
application/json
Output
JSON

Method Detail

Request Parameter Description Data Type Single/Multiple Required?
type
"write"
String
Single
Yes
layer
annotation layer id
String
Single
Yes
certificate
The certificate of the annotation to be removed.
JSON
Single
Yes

Example request:

POST http://localhost:8080/instagram/rest/v1.0/annotation/parlor-annotations/
{
    type: "write"
    layer: , "annotation-test-layer-id",
    certificate: {
        uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        timestamp: "1401830862"
    }
}

Example response:

{
}