Difference between revisions of "API"
From PhotoVoltaic Logger new generation
(Created page with "== Abstract == <blockquote>An application programming interface (API) is a protocol intended to be used as an interface by software components to communicate with each other....") |
m (→Data readout) |
||
| Line 30: | Line 30: | ||
The model behind the channel provides a defined interface to query data. | The model behind the channel provides a defined interface to query data. | ||
| + | |||
| + | === Parameters === | ||
| + | |||
| + | All parameters are optional. | ||
| + | |||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! Parameter name !! Description !! Format !! default !! Examples | ||
| + | |- | ||
| + | | <tt>start</tt> || Start timestamp for readout || string || <tt>00:00</tt> || | ||
| + | <tt>YYYY-mm-dd HH:ii:ss<br />seconds since 1970<br />[http://php.net/manual/en/datetime.formats.relative.php relative] from now<br />sunrise<ref name="daylight">needs location defined in in <tt>config/config.php</tt></ref></tt> | ||
| + | |- | ||
| + | | <tt>end</tt> || End timestamp for readout || string || <tt>24:00</tt> || | ||
| + | <tt>YYYY-mm-dd HH:ii:ss<br />seconds since 1970<br />[http://php.net/manual/en/datetime.formats.relative.php relative] from now<br />sunset<ref name="daylight" /></tt> | ||
| + | |- | ||
| + | | <tt>period</tt> || Example || string || <tt><empty></tt> || | ||
| + | <tt>[0-9.]+minutes<br />[0-9.]+hours<br />[0-9.]+days<br />[0-9.]+weeks<br />[0-9.]+month<br />[0-9.]+quarters<br />[0-9.]+years | ||
| + | <br />last<ref>returns the last reading for selected start-end range, can be empty, if no data in range, also relevant for meter channels</ref> | ||
| + | <br />readlast<ref>returns the last reading, ignores start-end range</ref> | ||
| + | <br />all</tt> | ||
| + | |- | ||
| + | | <tt>attributes</tt> || Return channel attributes as 1<sup>st</sup> data set / line || bool<ref name="bool">All of <tt>(1|x|yes|on|true)</tt> are interpreted case-insensitive as TRUE.</ref> || <tt>0</tt> || Example | ||
| + | |- | ||
| + | | <tt>full</tt> || Return all<ref>datetime, timestamp, data, min, max, count, timediff, consumption</ref> data, not only timestamp and value || bool<ref name="bool" /> || <tt>0</tt> || Example | ||
| + | |- | ||
| + | | <tt>short</tt> || JSON: Return data as numeric indexed array, not as object with named keys || bool<ref name="bool" /> || <tt>0</tt> || Example | ||
| + | |} | ||
| + | |||
| + | <references /> | ||
Revision as of 09:08, 28 February 2014
Abstract
An application programming interface (API) is a protocol intended to be used as an interface by software components to communicate with each other." -- Wikipedia:API
The API is implemented as a RESTful API, so it uses HTTP requests to store and read data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.
PVLng supports all of them:
- PUT = create
- GET = read
- POST = update
- DELETE = delete
Data storage
For data storage we have two possibilities:
- Web front end for the master data, like channels and their relationships
- HTTP REST API for the operational channel data with HTTP PUT requests
The storage API accepts only one parameter data and routes it to the requested channel.
By default (load live data) system date and time will be used.
The model behind the channel represents the interface to the database.
Data readout
The data readout from the system must be done with HTTP GET requests.
The readout API analyzes the requests, identifies the channel and returns the extracted data.
The model behind the channel provides a defined interface to query data.
Parameters
All parameters are optional.
| Parameter name | Description | Format | default | Examples |
|---|---|---|---|---|
| start | Start timestamp for readout | string | 00:00 |
YYYY-mm-dd HH:ii:ss |
| end | End timestamp for readout | string | 24:00 |
YYYY-mm-dd HH:ii:ss |
| period | Example | string | <empty> |
[0-9.]+minutes |
| attributes | Return channel attributes as 1st data set / line | bool[4] | 0 | Example |
| full | Return all[5] data, not only timestamp and value | bool[4] | 0 | Example |
| short | JSON: Return data as numeric indexed array, not as object with named keys | bool[4] | 0 | Example |
- ↑ 1.0 1.1 needs location defined in in config/config.php
- ↑ returns the last reading for selected start-end range, can be empty, if no data in range, also relevant for meter channels
- ↑ returns the last reading, ignores start-end range
- ↑ 4.0 4.1 4.2 All of (1|x|yes|on|true) are interpreted case-insensitive as TRUE.
- ↑ datetime, timestamp, data, min, max, count, timediff, consumption
