Skip to content

api.md

Latest commit

 

History

History
226 lines (182 loc) · 5.88 KB

api.md

File metadata and controls

226 lines (182 loc) · 5.88 KB
sidebar_label REST API
hide_table_of_contents true

REST API

The api node-type allows the exchange of signals via a simple REST API.

The provided REST API aims at implementing the Universal Data-exchange API drafted by the ERIGrid 2.0 project.

Compatability

VILLASnode implements currently version v2 of the Universal Data-exchange API.

Limitations

  • VILLASnode does not support the data-type string
  • VILLASnode does not support the payload-type events.
  • VILLASnode implements the API server side only.
    • VILLASnode might be extended in the future to act in the client role as well.
    • This would enable its use as the last-mile or RI-adapter.

Terminology

There are some slight differences in the terminology as used in the VILLASframework and universal API. The following table lists terms which are used synonymously:

VILLAS Universal API
signal channel

Prerequisites

This node-type requires VILLASweb to be compiled with web-support enabled (cmake -DWITH_WEB). This is the default if the libwebsockets library has been detected on the system.

Implementation

The source code of the node-type is available here: https://github.com/VILLASframework/node/blob/master/lib/nodes/api.cpp

Configuration {#config}

import ApiSchema from '@theme/ApiSchema';

Example

nodes = {
    api_node = {
        type = "api"

        in = {
            signals = (
                {
                    # Same as 'id' in uAPI context
                    name = ""

                    # A human readable description of the channel
                    description = "Volts on Bus A"

                    # Same as 'datatype' in uAPI context
                    type = "float"
                    unit = "V"
                    payload = "events" # Or 'samples'

                    # An expected refresh/sample rate of the signal
                    rate = 100.0

                    range = {
                        min = 20.0
                        max = 100.0
                    }

                    readable = true
                    writable = false
                }
            )
        }

        out = {
            signals = (
                # Similar to above
            )
        }
    }
}

Full config

http = {
    port = 8080
}

nodes = {
    api_node = {
        type = "api"

        in = {
            signals = (
                {
                    name = "sig1_in"
                    type = "float"
                    unit = "V"
                    description = "Signal 1"
                    rate = 100
                    readable = true
                    writable = false
                    payload = "samples"
                },
                {
                    name = "sig2_in"
                    type = "float"
                    unit = "A"
                    description = "Signal 1"
                    rate = 100
                    readable = true
                    writable = false
                    payload = "samples"
                },
                {
                    name = "sig3_in"
                    type = "float"
                    unit = "A"
                    description = "Signal 1"
                    rate = 100
                    readable = true
                    writable = false
                    payload = "samples"
                }
            )
        }

        out = {
            signals = (
                # Output signals have no name, type and unit settings as those are implicitly
                # derived from the signals which are routed to this node
                {
                    description = "Signal 1"
                    rate = 100
                    readable = true
                    writable = false
                    payload = "samples"
                },
                {
                    description = "Signal 1"
                    rate = 100
                    readable = true
                    writable = false
                    payload = "samples"
                },
                {
                    description = "Signal 1"
                    rate = 100
                    readable = true
                    writable = false
                    payload = "samples"
                }
            )
        }
    }

    signal_node = {
        type = "signal"

        signal = "mixed"
        values = 5
        rate = 1.0
    }
}

paths = (
    {
        in = [
            "api_node"
        ]

        hooks = (
            "print"
        )
    },
    {
        in = [
            "signal_node"
        ]
        out = [
            "api_node"
        ]
        hooks = (
            "print"
        )
    }
)

Usage

The following curl commands demonstrate the usage of the REST API node-type. For a full reference of the API, please have a look at the official API spec at the ERIGrid API repository.

:::note Please make sure to substitute api_node with the actual name or UUID of your node. :::

Get list of channels provided by the node

curl -v http://localhost:80/api/v2/universal/api_node/channels

Get current value of a signal by its ID

curl -v http://localhost:80/api/v2/universal/api_node/channel/ramp/sample

Update signal value by its ID

curl -v -XPUT -d '{"timestamp": 1648482084.1462665,"value":1234.0}' http://localhost:80/api/v2/universal/api_node/channel/signal0/sample