Data interface (REST)
The data interface is implemented as a REST/HTTP interface. The data interface makes it possible to retrieve data from Datahub, for example, directly to an online service offered by a market party to its end customers. It is not possible to report data to Datahub through the data interface. Market parties can choose if they want to use the data interface for the retrieval of information.
Parties’ rights to data are taken into account by the same rules for both the data interface and the event interface. A party can only retrieve information they are authorized to on the basis of an agreement with or an authorization from a customer.
If a market party needs to retrieve a large amount of data from Datahub, for example, to compare the data in their own data systems to the data in the Datahub, it does so via control reports. These reports can be run as scheduled reports at nighttime, when they do not affect normal daily processes.
The data interface provides the following data retrievals:
Retrieval of accounting point data
Retrieval of agreement information for an accounting point
Retrieval of metering data for an accounting point
Retrieval of authorization information for an accounting point
Retrieval of customer information
Retrieval of market party information
For market party information, data for all parties can be retrieved at a time.
To ensure data privacy, the retrieving party must always enter the customer ID of the customer with whom it has an agreement. One customer ID is sufficient even if the contract has more than one customer.
How the data interface is used is described in more detail under DH-1000 Retrieving accounting point information.
Recommendations for use of data interface
The REST data interface is not intended for mass queries. In the data interface, information is always retrieved one data set at a time. This means that a query must include an identifier such as the accounting point ID to retrieve the data. If a party wants to retrieve data for multiple accounting points at once, the Event interface SOAP is a more efficient way to retrieve this data.
An additional advantage of the SOAP interface is that Datahub automatically notifies all authorized parties of any changes to the data. The REST API users must manually submit queries for any updated data.
Restrictions on use of data interface
Information cannot be submitted to Datahub using the REST data interface.
The data interface does not offer functionality similar to the accounting point identification request event in the SOAP event interface. The requested data must always be specified individually, meaning that the query must always include an identifier like the accounting point ID or customer ID.
The data interface does not support delegations between market parties.
When acting as a third party, a market party always needs to have an authorization granted by the end customer before being able to retrieve any data. This authorization is always specific to customer and accounting point.
Examples of how to use data interface
The data interface can be used when an external registered party (third party or other market party) develops and creates new services. A third party service could be a mobile application that allows the end user to see information for all their accounting points, regardless of grid area or electricity supplier. This use case always requires an authorization granted by the customer. Whenever a party retrieves customer information, it must provide the customer ID. Datahub checks whether the requesting party has the right to the customer’s data and returns the data only if this is the case.
Request example:
Customer information retrieval, GetCustomerData (DH-1005)
The customer identification (personal identity code or company ID) must be provided.
The requesting party needs to have the right to the data (a valid authorization or contract).
The request returns accounting points where the customer has contracts.