Personal tools

Difference between revisions of "API"

From PhotoVoltaic Logger new generation

Jump to: navigation, search
m (Data readout)
m
 
(49 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Abstract ==
+
[[Category:API]]{{TOCright}}
 +
<blockquote>An application programming interface (API) is a protocol intended to be used as an interface by software components to communicate with each other.
 +
<cite>[[Wikipedia:API]]</cite></blockquote>
  
<blockquote>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]]</blockquote>
+
The API is implemented as a [[Wikipedia:REST|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.
  
The API is implemented as a [[Wikipedia:REST|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.
+
You can query the actual API version with  <tt><nowiki>http://your.domain.here/api/version</nowiki></tt><br />
 +
Make sure you request latest API version with <tt><nowiki>http://your.domain.here/api/latest/...</nowiki></tt> (from PVLng '''2.12.0''' and PVLng-scripts '''1.6.0''' onward)
  
PVLng supports all of them:
+
(see [[:Category:API|API r*]] pages for supported API versions)
* <tt>PUT</tt> = create
+
 
* <tt>GET</tt> = read
+
PVLng supports these request types:
* <tt>POST</tt> = update
+
{| class="wikitable"
* <tt>DELETE</tt> = delete
+
|-
 +
! Request method !! Action
 +
|-
 +
| <tt>PUT</tt> || '''Create''' data set
 +
|-
 +
| <tt>GET</tt> || '''Read''' data set(s)
 +
|-
 +
| <tt>POST</tt> || '''Update''' data set
 +
|-
 +
| <tt>DELETE</tt> || '''Delete''' data set
 +
|}
  
 
== Data storage ==
 
== Data storage ==
  
 
For data storage we have two possibilities:
 
For data storage we have two possibilities:
* Web front end for the master data, like channels and their relationships
+
* Web frontend for the master data, like channels and their relationships
* HTTP REST API for the operational channel data with HTTP PUT requests
+
* HTTP REST API for the operational channel data with HTTP PUT requests like [[Data storage example|this example]]
  
 
The storage API accepts only one parameter <tt>data</tt> and routes it to the requested channel.
 
The storage API accepts only one parameter <tt>data</tt> and routes it to the requested channel.
Line 24: Line 37:
  
 
== Data readout ==
 
== Data readout ==
 +
 +
''This section describes only the readout of measuring data via API, see the detailed [[API help]] for more supported actions.''
  
 
The data readout from the system must be done with HTTP GET requests.
 
The data readout from the system must be done with HTTP GET requests.
Line 30: Line 45:
  
 
The model behind the channel provides a defined interface to query data.
 
The model behind the channel provides a defined interface to query data.
 +
 +
=== Requested format ===
 +
 +
The returned content type is detected by the requested file extension
 +
 +
{| class="wikitable"
 +
|-
 +
! Extension !! Format !! Content type
 +
|-
 +
| <tt>.json</tt> || JSON (default, if no extension is set) || <tt>application/json</tt>
 +
|-
 +
| <tt>.csv</tt> || Semicolon separated values || <tt>application/csv</tt>
 +
|-
 +
| <tt>.tsv</tt> || TAB separated values || <tt>application/tsv</tt>
 +
|-
 +
| <tt>.txt</tt> || Space separated values<br />(proposed for single attribute requests) || <tt>text/plain</tt>
 +
|}
  
 
=== Parameters ===
 
=== Parameters ===
Line 40: Line 72:
 
|-
 
|-
 
| <tt>start</tt> || Start timestamp for readout || string || <tt>00:00</tt> ||
 
| <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>YYYY-mm-dd HH:ii:ss
 +
* seconds since 1970
 +
* [http://php.net/manual/datetime.formats.relative.php relative] from now
 +
* sunrise<ref name="daylight">needs the <tt>location</tt> defined in in <tt>config/config.php</tt></ref></tt>
 
|-
 
|-
 
| <tt>end</tt> || End timestamp for readout || string || <tt>24:00</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>YYYY-mm-dd HH:ii:ss
 +
* seconds since 1970
 +
* [http://php.net/manual/datetime.formats.relative.php relative] from now
 +
* sunset<ref name="daylight">needs the <tt>location</tt> defined in in <tt>config/config.php</tt></ref></tt>
 
|-
 
|-
| <tt>period</tt> || Example  || string || <tt>&lt;empty&gt;</tt> ||  
+
| <tt>period</tt> || Example  || string || <tt>&lt;empty&gt;</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
+
* <tt>[1-9][0-9]*minutes
<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>
+
* [1-9][0-9]*hours
<br />readlast<ref>returns the last reading, ignores start-end range</ref>
+
* [1-9][0-9]*days
<br />all</tt>
+
* [1-9][0-9]*weeks
 +
* [1-9][0-9]*month
 +
* [1-9][0-9]*quarters
 +
* [1-9][0-9]*years
 +
* 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>
 +
* readlast<ref>returns the last reading, ignores start-end range</ref>
 +
* all<ref>returns '''all''' readings, ignores start-end range, useful for full backup</ref></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>attributes</tt> || Return channel attributes as 1<sup>st</sup> data set || bool<ref name="bool">All of <tt>(1|x|yes|on|true)</tt> are interpreted case-insensitive as TRUE.</ref> || <tt>0</tt> || <tt>yes</tt>
 
|-
 
|-
| <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>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> || <tt>X</tt>
 
|-
 
|-
| <tt>short</tt> || JSON: Return data as numeric indexed array, not as object with named keys || bool<ref name="bool" /> || <tt>0</tt> || Example
+
| <tt>short</tt> || JSON: Return data as numeric indexed array,<br />not as object with named keys || bool<ref name="bool" /> || <tt>0</tt> || <tt>On</tt>
 
|}
 
|}
  
 
<references />
 
<references />
 +
 +
=== Result ===
 +
 +
If parameter <tt>attributes=1</tt> is set, the 1<sup>st</sup> data set will contain the channel attributes and further rows the following fields. This is required e.g. in Web frontends [[charts module]] AJAX calls which need the channel attributes for drawing and so '''only one''' call is required to fetch attributes '''and''' data.
 +
Data are not rounded at all, they are delivered as stored or calculated.
 +
 +
By default, only the '''timestamp''' and '''data''' values will be returned. If you set the request parameter <tt>full=1</tt>, all the following data are returned.
 +
 +
{| class="wikitable"
 +
|-
 +
! Field !! Description
 +
|-
 +
| <tt>datetime</tt> || A readable timestamp; mostly used for debugging
 +
|-
 +
| <tt>timestamp</tt> || UTC Timestamp, good for direct use in graphing
 +
|-
 +
| <tt>data</tt> || Reading value for this timestamp
 +
|-
 +
| <tt>min</tt> || Minimal value of consolidated data
 +
|-
 +
| <tt>max</tt> || Maximal value of consolidated data
 +
|-
 +
| <tt>count</tt> || Count of consolidated data sets for returned row
 +
|-
 +
| <tt>timediff</tt> || Time range of the consolidation in seconds
 +
|-
 +
| <tt>consumption</tt> || For meter channels the difference during time period (last datas et to this data set)
 +
|}
 +
 +
== Return codes ==
 +
 +
The status code will be doubled into the response header and the response body.
 +
This offers the possibility to analyze either the header or the body to check for success or errors.
 +
For every request the response body will contain further information, especially in case of an error.
 +
The following subset of HTTP status codes<ref>http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</ref> are used by the API.
 +
 +
=== 200 - OK ===
 +
 +
The request has succeeded
 +
* Read of data was successful
 +
* Data was error free, but not saved
 +
** Insert data within 5 seconds interval will be ignored (adjustable in database table <tt>pvlng_config -> DoubleRead</tt>)
 +
** Not changed Switcher states will be ignored
 +
 +
=== 201 - Created ===
 +
 +
The request has been fulfilled and resulted in a new resource being created
 +
* Data was successful saved
 +
* On batch loads the response body contains the count of inserted data sets.
 +
 +
=== 204 - No Response ===
 +
 +
The server has fulfilled the request but does not need to return an entity-body
 +
* Response for a <tt>DELETE</tt> request
 +
 +
=== 400 - Bad Request ===
 +
 +
The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
 +
* There was mostly a problem during data readout
 +
* See response body for details
 +
 +
=== 401 - Unauthorized ===
 +
 +
The request requires user authentication
 +
* Missing or wrong API key for <tt>PUT</tt> requests
 +
* Missing or wrong API key for <tt>GET</tt> requests for '''private''' channels, they are only accessible with [[Security system#API key|API key]].
 +
 +
=== 405 - Method Not Allowed ===
 +
 +
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI
 +
* Only <tt>PUT / GET / POST / DELETE</tt> are allowed
 +
 +
=== 500 - Internal Server Error ===
 +
 +
The server encountered an unexpected condition which prevented it from fulfilling the request.
 +
* See response body for details
 +
 +
<references/>

Latest revision as of 14:04, 17 February 2015

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.

You can query the actual API version with http://your.domain.here/api/version
Make sure you request latest API version with http://your.domain.here/api/latest/... (from PVLng 2.12.0 and PVLng-scripts 1.6.0 onward)

(see API r* pages for supported API versions)

PVLng supports these request types:

Request method Action
PUT Create data set
GET Read data set(s)
POST Update data set
DELETE Delete data set

Data storage

For data storage we have two possibilities:

  • Web frontend for the master data, like channels and their relationships
  • HTTP REST API for the operational channel data with HTTP PUT requests like this example

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

This section describes only the readout of measuring data via API, see the detailed API help for more supported actions.

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.

Requested format

The returned content type is detected by the requested file extension

Extension Format Content type
.json JSON (default, if no extension is set) application/json
.csv Semicolon separated values application/csv
.tsv TAB separated values application/tsv
.txt Space separated values
(proposed for single attribute requests)
text/plain

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
  • seconds since 1970
  • relative from now
  • sunrise[1]
end End timestamp for readout string 24:00
  • YYYY-mm-dd HH:ii:ss
  • seconds since 1970
  • relative from now
  • sunset[1]
period Example string <empty>
  • [1-9][0-9]*minutes
  • [1-9][0-9]*hours
  • [1-9][0-9]*days
  • [1-9][0-9]*weeks
  • [1-9][0-9]*month
  • [1-9][0-9]*quarters
  • [1-9][0-9]*years
  • last[2]
  • readlast[3]
  • all[4]
attributes Return channel attributes as 1st data set bool[5] 0 yes
full Return all[6] data, not only timestamp and value bool[5] 0 X
short JSON: Return data as numeric indexed array,
not as object with named keys
bool[5] 0 On
  1. 1.0 1.1 needs the location defined in in config/config.php
  2. returns the last reading for selected start-end range, can be empty, if no data in range, also relevant for meter channels
  3. returns the last reading, ignores start-end range
  4. returns all readings, ignores start-end range, useful for full backup
  5. 5.0 5.1 5.2 All of (1|x|yes|on|true) are interpreted case-insensitive as TRUE.
  6. datetime, timestamp, data, min, max, count, timediff, consumption

Result

If parameter attributes=1 is set, the 1st data set will contain the channel attributes and further rows the following fields. This is required e.g. in Web frontends charts module AJAX calls which need the channel attributes for drawing and so only one call is required to fetch attributes and data. Data are not rounded at all, they are delivered as stored or calculated.

By default, only the timestamp and data values will be returned. If you set the request parameter full=1, all the following data are returned.

Field Description
datetime A readable timestamp; mostly used for debugging
timestamp UTC Timestamp, good for direct use in graphing
data Reading value for this timestamp
min Minimal value of consolidated data
max Maximal value of consolidated data
count Count of consolidated data sets for returned row
timediff Time range of the consolidation in seconds
consumption For meter channels the difference during time period (last datas et to this data set)

Return codes

The status code will be doubled into the response header and the response body. This offers the possibility to analyze either the header or the body to check for success or errors. For every request the response body will contain further information, especially in case of an error. The following subset of HTTP status codes[1] are used by the API.

200 - OK

The request has succeeded

  • Read of data was successful
  • Data was error free, but not saved
    • Insert data within 5 seconds interval will be ignored (adjustable in database table pvlng_config -> DoubleRead)
    • Not changed Switcher states will be ignored

201 - Created

The request has been fulfilled and resulted in a new resource being created

  • Data was successful saved
  • On batch loads the response body contains the count of inserted data sets.

204 - No Response

The server has fulfilled the request but does not need to return an entity-body

  • Response for a DELETE request

400 - Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

  • There was mostly a problem during data readout
  • See response body for details

401 - Unauthorized

The request requires user authentication

  • Missing or wrong API key for PUT requests
  • Missing or wrong API key for GET requests for private channels, they are only accessible with API key.

405 - Method Not Allowed

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI

  • Only PUT / GET / POST / DELETE are allowed

500 - Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

  • See response body for details