The Temetra API uses REST to provide access to underlying data stored in Temetra without the need to maintain a fixed format internally. As meter reading technology changes over time, it’s necessary to update the stored data, and an API allows a fixed interface to the data for external use, while the underly data structures are changed to incorporate new technologies.
For a description of REST principles see http://en.wikipedia.org/wiki/Representational_state_transfer
REST allows the data can be retrieved using a web browser, or command line tools such as curl, making it very easy to debug and and test consumers of Temetra data. Almost every programming language has support for http protocol, and because all comms is over a single TCP/IP port 443, it simplifies the interface, without the need for VPN or firewall modifications.
Temetra uses the http service methods to provide read/write access to underlying data repository, using standard REST semantics.
- GET retrieve one or more objects
- POST create a new object – POST is not idempotent
- PUT update or replace an existing object – PUT is idempotent
- DELETE delete an object
Standard http status codes are returned: 200 for success, 400 for bad request, 401 for unauthorized etc
Temetra provides some additional information where appropriate with error return codes, encoded in the requested data format (XML/JSON see below).
Character set and formatting
REST does mandate a character set, or formatting for items like dates. Temetra always returns UTF-8, and while we accept all standard character sets, we recommend using UTF-8 also for submitted data.
Date+Time are formatted as ISO8601 yyyy-MM-dd’T’HH:mm:ss’Z’
Security and authentication
All comms with Temetra is over https, with SSL providing end to end encryption (AES256/SHA1).
Authentication is by way of tokens issued for each client use. These are very large number encoded as alphanumeric strings, issued by Temetra using a strong random number generator.
Tokens provide read-only or read/write access to a single network on Temetra, and may be restricted to specific data groups.
As a further security restriction, tokens can be restricted to access from specific IP addresses, and can be revoked/disabled.
To mitigate against token searches, any client IP address that fails authentication 50 times is automatically disabled from any access.