Difference between revisions of "API"
From PhotoVoltaic Logger new generation
m (→Abstract) |
m (→401 - Unauthorized) |
||
Line 136: | Line 136: | ||
The request requires user authentication | The request requires user authentication | ||
− | * Missing or wrong API key for PUT requests | + | * 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#API key]]. | ||
=== 405 - Method Not Allowed === | === 405 - Method Not Allowed === |
Revision as of 16:01, 3 March 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
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 | |
end | End timestamp for readout | string | 24:00 | |
period | Example | string | <empty> | |
attributes | Return channel attributes as 1st data set / line | 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.0 1.1 needs the 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
- ↑ returns all readings, ignores start-end range, useful for full backup
- ↑ 5.0 5.1 5.2 All of (1|x|yes|on|true) are interpreted case-insensitive as TRUE.
- ↑ datetime, timestamp, data, min, max, count, timediff, consumption
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 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 security#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