ERIGrid Universal Data Exchange API (v2.0)
Download OpenAPI specification:Download
A common API used by ERIGrid research infrastructures to exchange signals for geographically distributed experiments.
Each implementation of the universal API is free to implement a subset of the endpoints specified by this API. The transports shall document which features are implemented and return a 501 "Not Implemented" HTTP status code in case an unsupported endpoint is used.
The universal API uses the HTTP status codes an maps them accordingly. All requests to the API must return a response body of Content-type "application/json". This also applies to failed requests (status codes 400 - 599).
Operator
An operator is a software component which interprets a global experiment configuration and processes it for configuring assets of an experiment.
An example of such an asset can be data-exchange transports, or lab equipment.
Middleware
Collection of services developed in the ERIGrid 2.0 project to facilitate interconnection of extended RIs.
This includes data-exchange, configuration management, time-sychronization, etc...
Server
An HTTP server implementing the Universal API which is accessed by the clients.
Implemented by a transport.
Transport
External tool to facilitate data-exchange between RIs.
Examples of current implementations are VILLAS, Jander, LabLink.
In the context of the ERIGrid middleware the transport is one of the assets which is managed by an operator.
Client
A HTTP client implementing the Universal API which makes requests towards a server.
Node
A software instance of the transport solution typically deployed in each RI.
Examples of node can be a Raspberry Pi or Virtual Machine.
RI Adapter
RI-specific data-exchange software client between the RI SCADA / equipment and the uAPI server.
Channel
A source or sink of samples or events at a single point.
Examples are measurement, set points, states or commands and events.
Sample
Describes the snapshot of value and additional attributes of a channel at a specific point in time.
It contains a value and metadata attributes such as quality and timestamp.
Samples are usually acquired or updated on a periodical basis.
Event
In contrast to a sample, events are an asynchronous, non-continuous actions/stimulus.
For example, they can be used to represent control commands or fault events and state changes.
Value
A value is key payload (i.e. not metadata) of a sample.
The development of JRA3.1 API has been supported by the ERIGrid 2.0 project of the H2020 Programme under Grant Agreement No. 870620
Get the last sample of a channel
path Parameters
| id required | string (Channel ID) ^[a-zA-Z0-9-_/.:]+$ Examples: DTU::Storage_Vanadium:M_EA_Watt.instMag DTU::Storage_Vanadium:M_EA_Var.instMag DTU::Instrument_715-2.Gaia:M_EA_Watt.instMag DTU::Storage_Vanadium:S_EA_Hz.instMag A globally unique identifier for the channel |
Responses
Response samples
- 200
{- "timestamp": 1644407419.123,
- "timesource": "synchronized",
- "value": 230.4,
- "validity": "unknown",
- "source": "unknown"
}Update sample of a channel
path Parameters
| id required | string (Channel ID) ^[a-zA-Z0-9-_/.:]+$ Examples: DTU::Storage_Vanadium:M_EA_Watt.instMag DTU::Storage_Vanadium:M_EA_Var.instMag DTU::Instrument_715-2.Gaia:M_EA_Watt.instMag DTU::Storage_Vanadium:S_EA_Hz.instMag A globally unique identifier for the channel |
Request Body schema: application/json
| timestamp required | number (Signal timestamp) A point in time when this signal has been measured or generated by a contoller or simulator. Provided as floating point UNIX timestamp |
| timesource | string Default: "unknown" Enum: "synchronized" "unsynchronized" "unknown" |
required | (A value of a sample or event (number)) or (A value of a sample or event (integer)) or (A value of a sample or event (boolean)) or (A value of a sample or event (string)) or (A value of a sample or event (object)) (A value of a sample or event) |
| validity | string Default: "unknown" Enum: "unknown" "valid" "invalid" "questionable" "indeterminate" |
| source | any Default: "unknown" Enum: "unknown" "process" "test" "calculated" "simulated" |
Responses
Request samples
- Payload
{- "timestamp": 1644407419.123,
- "timesource": "synchronized",
- "value": 230.4,
- "validity": "unknown",
- "source": "unknown"
}Get events from a channel
path Parameters
| id required | string (Channel ID) ^[a-zA-Z0-9-_/.:]+$ Examples: DTU::Storage_Vanadium:M_EA_Watt.instMag DTU::Storage_Vanadium:M_EA_Var.instMag DTU::Instrument_715-2.Gaia:M_EA_Watt.instMag DTU::Storage_Vanadium:S_EA_Hz.instMag A globally unique identifier for the channel |
query Parameters
| since_id | integer (EventId) The oldest event ID the requester does not want to request. |
Responses
Send event to channel
path Parameters
| id required | string (Channel ID) ^[a-zA-Z0-9-_/.:]+$ Examples: DTU::Storage_Vanadium:M_EA_Watt.instMag DTU::Storage_Vanadium:M_EA_Var.instMag DTU::Instrument_715-2.Gaia:M_EA_Watt.instMag DTU::Storage_Vanadium:S_EA_Hz.instMag A globally unique identifier for the channel |
Request Body schema: application/json
| timestamp required | number (Signal timestamp) A point in time when this signal has been measured or generated by a contoller or simulator. Provided as floating point UNIX timestamp |
| timesource | string Default: "unknown" Enum: "synchronized" "unsynchronized" "unknown" |
required | (A value of a sample or event (number)) or (A value of a sample or event (integer)) or (A value of a sample or event (boolean)) or (A value of a sample or event (string)) or (A value of a sample or event (object)) (A value of a sample or event) |
| validity | string Default: "unknown" Enum: "unknown" "valid" "invalid" "questionable" "indeterminate" |
| source | any Default: "unknown" Enum: "unknown" "process" "test" "calculated" "simulated" |
| id | integer (EventId) A monotonically incremented ID identifying an event. Only present in events returned by the server |
Responses
Request samples
- Payload
[- {
- "timestamp": 1644407419.123,
- "timesource": "synchronized",
- "value": 230.4,
- "validity": "unknown",
- "source": "unknown",
- "id": 0
}
]