Skip to content

API

Document Status

Work in Progress

Well known API endpoints

This document summarises the Tremor REST API

Url Description
http://localhost:9898/ The default ( development ) endpoint on a local ( development ) host

Paths

The endpoint paths supported by the Tremor REST API

GET /onramp

Lists onramps

Description:

Returns a list of identifiers for each onramp stored in the repository

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

find_onramps

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/registry_set
200 application/yaml #/components/schemas/registry_set

POST /onramp

Publish a new onramp to the tremor artefact repository

Description:

Publishes a new onramp to the tremor artefact repository if the artefact id is unique.

Returns artefact data, on success.

If an onramp of the same name already exists, a conflict error is returned.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

publish_onramp

Returns:

Status Code Content Type Schema Type
201 application/json #/components/schemas/onramp
201 application/yaml #/components/schemas/onramp
409 empty no content

GET /onramp/{artefact-id}

Finds onramp data from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

get_onramp_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/onramp_state
200 application/yaml #/components/schemas/onramp_state
404 empty no content

DELETE /onramp/{artefact-id}

Remove an onramp from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns old artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

delete_onramp_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/onramp
200 application/yaml #/components/schemas/onramp
409 empty no content
404 empty no content

GET /offramp

Lists oframps

Description:

Returns a list of identifiers for each offramp stored in the repository

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

find_offramps

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/registry_set
200 application/yaml #/components/schemas/registry_set

POST /offramp

Publish a new offramp to the tremor artefact repository

Description:

Publishes a new offramp to the tremor artefact repository if the artefact id is unique.

Returns artefact data, on success.

If an arterfact of the same name already exists, a conflict error is returned.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

publish_offramp

Returns:

Status Code Content Type Schema Type
201 application/json #/components/schemas/offramp
201 application/yaml #/components/schemas/offramp
409 empty no content

GET /offramp/{artefact-id}

Get offramp data from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

get_offramp_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/offramp_state
200 application/yaml #/components/schemas/offramp_state
404 empty no content

DELETE /offramp/{artefact-id}

Remove artefact from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns old artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

delete_offramp_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/offramp
200 application/yaml #/components/schemas/offramp
409 empty no content
404 empty no content

GET /pipeline

Lists pipelines

Description:

Returns a list of identifiers for each pipeline stored in the repository

Response data is a trickle source code string.

OperationId:

find_pipelines

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/registry_set
200 application/yaml #/components/schemas/registry_set

POST /pipeline

Publish a new pipeline to the tremor artefact repository

Description:

Publishes a new pipeline to the tremor artefact repository if the artefact id is unique.

The request body need to be valid trickle.

Returns artefact data, on success.

If an pipeline of the same name already exists, a conflict error is returned.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

publish_pipeline

Returns:

Status Code Content Type Schema Type
201 application/json #/components/schemas/pipeline
201 application/yaml #/components/schemas/pipeline
201 application/vnd.trickle #/components/schemas/pipeline
409 empty no content

GET /pipeline/{artefact-id}

Get pipeline data from tremor artefact repository

Description:

Given a valid pipeline artefact identifier of a pipeline artefact stored in the tremor artefact repository

Returns pipeline source code string, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ), but is essentially a trickle source code string.

OperationId:

get_pipeline_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/pipeline
200 application/yaml #/components/schemas/pipeline
200 application/vnd.trickle #/components/schemas/pipeline
404 empty no content

DELETE /pipeline/{artefact-id}

Remove pipeline from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns old artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

delete_pipeline_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/pipeline
200 application/yaml #/components/schemas/pipeline
200 application/vnd.trickle #/components/schemas/pipeline
409 empty no content
404 empty no content

GET /binding

Lists bindings

Description:

Returns a list of identifiers for each binding stored in the repository

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

find_bindings

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/registry_set
200 application/yaml #/components/schemas/registry_set

POST /binding

Publish a new binding to the tremor artefact repository

Description:

Publishes a new binding to the tremor artefact repository if the artefact id is unique.

Returns artefact data, on success.

If an arterfact of the same name already exists, a conflict error is returned.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

publish_binding

Returns:

Status Code Content Type Schema Type
201 application/json #/components/schemas/binding
201 application/yaml #/components/schemas/binding
409 empty no content

GET /binding/{artefact-id}

Get binding data from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

get_binding_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/binding_state
200 application/yaml #/components/schemas/binding_state
404 empty no content

DELETE /binding/{artefact-id}

Remove binding from tremor artefact repository

Description:

Given a valid artefact identifier of an artefact stored in the tremor artefact repository

Returns old artefact data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

delete_binding_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/binding
200 application/yaml #/components/schemas/binding
404 empty no content

GET /binding/{artefact-id}/{instance-id}

Get deployed artefact servant data from tremor artefact registry

Description:

Given a valid identifier of a binding artefact stored in the tremor artefact repository

Given a valid binding instance identifier for a deployed and running instance of the binding deployed and accesible via the tremor instance registry

Returns binding instance data on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

get_binding_instance_by_id

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/binding
200 application/yaml #/components/schemas/binding
404 empty no content

POST /binding/{artefact-id}/{instance-id}

Publish, deploy and activate a binding

Description:

Given a valid binding artefact identifier of a binding artefact stored in the tremor artefact repository

Given a valid binding instance identifier for a deployed and running instance of the binding deployed and accesible via the tremor instance registry

Creates new instances of artefacts ( if required ), publishes instances to the tremor instance registry. If instances are onramps, offramps or pipelines new registry values will be created. In the case of onramps and offramps these are deployed after any dependant pipeline instances and then they are interconnected.

Returns the binding instance data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

activate-binding

Returns:

Status Code Content Type Schema Type
201 application/json #/components/schemas/binding
201 application/yaml #/components/schemas/binding
404 empty no content

DELETE /binding/{artefact-id}/{instance-id}

Deactivate and unpublish deployed bindings

Description:

Given a valid binding artefact identifier of a binding artefact stored in the tremor artefact repository

Given a valid binding instance identifier for a deployed and running instance of the binding deployed and accesible via the tremor instance registry

Deactivates, stops and unpublishes the target instances and any dependant instances that are no longer referenced by the runtime.

Returns old instance data, on success.

Response data may be either JSON or YAML formatted ( defaults to JSON ).

OperationId:

deactivate-binding

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/binding
200 application/yaml #/components/schemas/binding
404 empty no content

GET /version

Get's the current version

Description:

This endpoint returns version information for the current version of tremor. Versioning policy follows Semantic Versioning

OperationId:

get_version

Returns:

Status Code Content Type Schema Type
200 application/json #/components/schemas/version

Schemas

JSON Schema for types defioned in the Tremor REST API

Schema for type: version

Version information

{
    "description": "Version information",
    "properties": {
        "additionalProperties": false,
        "debug": {
            "description": "True if this is a debug build",
            "type": "boolean"
        },
        "version": {
            "description": "The semantic version code",
            "type": "string"
        }
    },
    "required": [
        "version"
    ]
}

Schema for type: registry_set

A list of registry artefacts

{
    "description": "A list of registry artefacts",
    "items": {
        "$ref": "#/components/schemas/artefact_id"
    },
    "type": "array"
}

Schema for type: instance_set

A list of artefact instances

{
    "description": "A list of artefact instances",
    "items": {
        "$ref": "#/components/schemas/instance_id"
    },
    "type": "array"
}

Schema for type: artefact_id

No description.

{
    "pattern": "^[a-z][a-zA-Z_:]*$",
    "type": "string"
}

Schema for type: instance_id

No description.

{
    "$ref": "#/components/schemas/artefact_id"
}

Schema for type: port_id

No description.

{
    "$ref": "#/components/schemas/artefact_id"
}

Schema for type: artefact

No description.

{
    "oneOf": [
        {
            "$ref": "#/components/schemas/pipeline"
        },
        {
            "$ref": "#/components/schemas/onramp"
        },
        {
            "$ref": "#/components/schemas/offramp"
        },
        {
            "$ref": "#/components/schemas/binding"
        }
    ]
}

Schema for type: instance

No description.

{
    "oneOf": [
        {
            "$ref": "#/components/schemas/mapping"
        }
    ]
}

Schema for type: publish_ok

Response when a registry publish was succesful

{
    "description": "Response when a registry publish was succesful",
    "properties": {
        "id": {
            "$ref": "#/components/schemas/artefact_id",
            "description": "The id of the pubished artefact"
        }
    },
    "required": [
        "id"
    ]
}

Schema for type: pipeline

State of an pipeline, expressed as trickle source code.

{
    "description": "State of an pipeline, expressed as trickle source code.",
    "type": "string"
}

Schema for type: onramp_state

State of an onramp, including specification and instances

{
    "additionalProperties": false,
    "description": "State of an onramp, including specification and instances",
    "properties": {
        "artefact": {
            "$ref": "#/components/schemas/onramp"
        },
        "instances": {
            "$ref": "#/components/schemas/instance_set"
        }
    },
    "type": "object"
}

Schema for type: onramp

A tremor onramp specification

{
    "additionalProperties": false,
    "description": "A tremor onramp specification",
    "properties": {
        "codec": {
            "$ref": "#/components/schemas/codec"
        },
        "codec_map": {
            "$ref": "#/components/schemas/codec_map"
        },
        "config": {
            "description": "A map of key/value pairs used to configure this onramp",
            "type": "object"
        },
        "description": {
            "description": "Documentation for this type",
            "type": "string"
        },
        "err_required": {
            "description": "Whether a pipeline needs to be connected to the err port before startup",
            "type": "boolean"
        },
        "id": {
            "$ref": "#/components/schemas/artefact_id"
        },
        "linked": {
            "description": "Whether this offramp is linked or not",
            "type": "boolean"
        },
        "metrics_interval_s": {
            "description": "interval in which metrics info is published",
            "minimum": 0,
            "type": "integer"
        },
        "postprocessors": {
            "additionalItems": false,
            "items": {
                "$ref": "#/components/schemas/postprocessor"
            },
            "type": "array"
        },
        "preprocessors": {
            "additionalItems": false,
            "items": {
                "$ref": "#/components/schemas/preprocessor"
            },
            "type": "array"
        },
        "type": {
            "$ref": "#/components/schemas/onramp_type"
        }
    },
    "required": [
        "type",
        "id"
    ],
    "type": "object"
}

Schema for type: offramp_state

State of an offramp, including specification and instances

{
    "additionalProperties": false,
    "description": "State of an offramp, including specification and instances",
    "properties": {
        "artefact": {
            "$ref": "#/components/schemas/offramp"
        },
        "instances": {
            "$ref": "#/components/schemas/instance_set"
        }
    },
    "type": "object"
}

Schema for type: offramp

A tremor offramp specification

{
    "additionalProperties": false,
    "description": "A tremor offramp specification",
    "properties": {
        "codec": {
            "$ref": "#/components/schemas/codec"
        },
        "codec_map": {
            "$ref": "#/components/schemas/codec_map"
        },
        "config": {
            "description": "A map of key/value pairs used to configure this onramp",
            "type": "object"
        },
        "description": {
            "description": "Documentation for this type",
            "type": "string"
        },
        "id": {
            "$ref": "#/components/schemas/artefact_id"
        },
        "linked": {
            "description": "Whether this offramp is linked or not",
            "type": "boolean"
        },
        "metrics_interval_s": {
            "description": "interval in which metrics info is published",
            "minimum": 0,
            "type": "integer"
        },
        "postprocessors": {
            "additionalItems": false,
            "items": {
                "$ref": "#/components/schemas/postprocessor"
            },
            "type": "array"
        },
        "preprocessors": {
            "additionalItems": false,
            "items": {
                "$ref": "#/components/schemas/preprocessor"
            },
            "type": "array"
        },
        "type": {
            "$ref": "#/components/schemas/offramp_type"
        }
    },
    "required": [
        "type",
        "id"
    ],
    "type": "object"
}

Schema for type: binding_state

State of an binding, including specification and instances

{
    "additionalProperties": false,
    "description": "State of an binding, including specification and instances",
    "properties": {
        "artefact": {
            "$ref": "#/components/schemas/binding"
        },
        "instances": {
            "$ref": "#/components/schemas/instance_set"
        }
    },
    "type": "object"
}

Schema for type: binding

A tremor binding specification

{
    "additionalProperties": false,
    "description": "A tremor binding specification",
    "properties": {
        "description": {
            "type": "string"
        },
        "id": {
            "$ref": "#/components/schemas/artefact_id"
        },
        "links": {
            "$ref": "#/components/schemas/binding_map"
        }
    },
    "required": [
        "id",
        "links"
    ],
    "type": "object"
}

Schema for type: binding_map

A map of binding specification links

{
    "additionalProperties": false,
    "description": "A map of binding specification links",
    "patternProperties": {
        "^(tremor://localhost)?/(onramp|pipeline)/[a-zA-Z][A-Za-z0-9_]*/[a-zA-Z][A-Za-z0-9_]*$": {
            "additionalItems": false,
            "items": {
                "$ref": "#/components/schemas/binding_dst"
            },
            "type": "array"
        }
    },
    "type": "object"
}

Schema for type: binding_dst

No description.

{
    "pattern": "^(tremor://localhost)?/(pipeline|offramp)/[a-zA-Z][A-Za-z0-9_]*/[a-zA-Z][A-Za-z0-9_]*$",
    "type": "string"
}

Schema for type: mapping

A tremor mapping specification

{
    "description": "A tremor mapping specification",
    "type": "object"
}

Schema for type: offramp_type

supported offramp types

{
    "description": "supported offramp types",
    "enum": [
        "blackhole",
        "debug",
        "elastic",
        "exit",
        "file",
        "kafka",
        "newrelic",
        "postgres",
        "rest",
        "stderr",
        "stdout",
        "tcp",
        "udp",
        "ws"
    ],
    "type": "string"
}

Schema for type: onramp_type

supported onramp types

{
    "description": "supported onramp types",
    "enum": [
        "blaster",
        "crononome",
        "file",
        "kafka",
        "metronome",
        "postgres",
        "rest",
        "tcp",
        "udp",
        "ws"
    ],
    "type": "string"
}

Schema for type: codec

The data format supported for encoding/decoding to/from tremor types

{
    "description": "The data format supported for encoding/decoding to/from tremor types",
    "enum": [
        "binflux",
        "influx",
        "json",
        "msgpack",
        "null",
        "statsd",
        "string",
        "yaml"
    ],
    "type": "string"
}

Schema for type: codec_map

A map from mime-type to codec

{
    "additionalProperties": {
        "$ref": "#/components/schemas/codec"
    },
    "description": "A map from mime-type to codec",
    "type": "object"
}

Schema for type: preprocessor

Supported preprocessors

{
    "description": "Supported preprocessors",
    "enum": [
        "base64",
        "decompress",
        "gelf-chunking",
        "gzip",
        "length-prefixed",
        "lines",
        "lines-null",
        "lines-pipe",
        "lines-no-buffer",
        "lines-cr-no-buffer",
        "lz4",
        "remove-empty",
        "snappy",
        "xz",
        "zlib"
    ],
    "type": "string"
}

Schema for type: postprocessor

Supported postprocessors

{
    "description": "Supported postprocessors",
    "enum": [
        "base64",
        "gelf-chunking",
        "gzip",
        "length-prefixed",
        "lines",
        "lz4",
        "snappy",
        "xz",
        "zlib"
    ],
    "type": "string"
}