User Guide

Demand Response Signal API

 

Version 1.2

Effective date: 21 December 2018

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Contents

1       Introduction_ 3

1.1      Definitions 3

1.2      Technical support 3

2       Functional description of the Demand Response Signal API 4

2.1      General description. 4

2.2      Prerequisites for using the APIs 4

2.2.1   Data confidentiality. 4

2.2.2   Termination. 4

2.3      “demand_response_signals" resource. 4

3       Accessing the API 5

4       Resource exposed by the “Demand Response Signal” API 6

4.1      "demand_response_signals" resource. 6

4.1.1   GET /demand_response_signals. 6

4.1.1.1     Call methods. 6

4.1.1.2     Inputs. 7

4.1.1.3     Outputs. 8

4.1.1.4     Control rules. 9

4.1.1.5     Error codes. 10

5       Details of errors_ 11

5.1      Functional errors 13

5.1.1   demand_response_signals. 13

5.2      Technical errors 14

END OF DOCUMENT_ 15


 

This document describes version 1 of the Demand Response Signal API that RTE provides for its Clients in order to obtain data signalled for the year within the framework of the demand response call for tenders.

Reference documents

 

Short reference

Document title

Complete reference

[R1]

Terms of use for RTE’s APIs

Access link

 

1.1     Definitions

The terms used in this User Guide (the first letters of which are always capitalised) are defined below. Otherwise, their definitions are given in the General Conditions of Use [R1]:

 

 

API

Application Programming Interface

Authentication

Protection Mode for ensuring that the identity of the Sender or Receiver has been verified by RTE, and that they are authorised to access the IT system and use the Applications.

Sender

Party which sends a Message.

Message 

Set of computer data used to transmit information, structured in accordance with a particular order that is specified in the User Guide. A Message can be sent by the User or by RTE.

Operation

An operation is the way in which the client interacts with the API's resource. An HTTP verb is always used (for example: GET for reading)

Party or Parties

Within the framework of the User Guide, these terms refer to either RTE or the User individually, or to both RTE and the User collectively.

Receiver

Party which receives the Sender's Message.

Resource

A resource is the data in relation to which the client application interacts.

URL

Uniform Resource Locator: character string based on a specific format used to locate a resource on a network and specify what protocol should be used on this resource.

User(s) 

Legal entity which has agreed to RTE’s General Terms and Conditions for Using APIs and which has been granted access to RTE’s IT system for the purposes of using the APIs it has made available.

1.2     Technical support

In the event of difficulties accessing or using an API, users can contact the telephone support services provided by RTE in accordance with the technical conditions detailed in the General Terms and Conditions of Use.

2.1     General description

The services provided by this API can be used to obtain data for days signalled in the year.

2.2     Prerequisites for using the APIs

The Demand Response Signal API is for stakeholders operating on the electricity market and the general public. However, users of the API will need to create an account on RTE's digital portal. Once they have set up an account, they'll be able to get their OAuth 2.0 credentials. These credentials are then required whenever calls are made to the APIs.

2.2.1   Data confidentiality

The information contained in the Messages may not be used for any purpose other than the ones described in the General Terms and Conditions of Use [R1].

2.2.2   Termination

A subscription to an API is automatically terminated when the user deletes their account on RTE's digital portal.

Should the User wish to cease using an API without terminating their subscription, they simply need to stop sending calls to it.

2.3     “demand_response_signals" resource

This service can be used to obtain signalling information for the current day and the next day (if no period is specified), or for the whole year (if parameters are entered).

3         Accessing the API

The REST protocol is used to access the API described in this document.

As is the case for all of the APIs provided by RTE, accessing and using them are subject to the provisions of the General Terms and Conditions of Use [R1].

The authorisation method for accessing the APIs is the OAuth framework, the applications of which are described in the FAQs.

4      Resource exposed by the “Demand Response Signal” API
4.1     "demand_response_signals" resource 4.1.1   GET /demand_response_signals 4.1.1.1               Call methods

The resource is exposed in the following way:

 

Exposure

REST / JSON

Method

GET

Resource URL

https://digital.iservices.rte-france.com/open_api/demand_response_signal/v1/demand_response_signals?start_date=<valeur>&end_date=<valeur>

 

Where the start_date and end_date parameters are the same as those sent to the resource by the caller.

Sandbox URL (1)

https://digital.iservices.rte-france.com/open_api/demand_response_signal/v1/sandbox/demand_response_signals

(1) The sandbox does not take the input parameters into account

 

Call recommendations

 

The purpose of this operation is to enable the retrieval of the signalling information. For nominal use, the period's fields do not need to be filled in. This service automatically returns the signalling information for the current day and the next day.

 

This service provides data available after 1 January 2019. Data for periods before this date is not available.

 


 

4.1.1.2 Inputs

 

NAME

DESCRIPTION

CARD.

TYPE

VALUES / FORMAT

RULES

start_date

Period start date

0..1

date
(2) (3)

YYYY-MM-DDThh:mm:sszzzzzz

SIGN-RG01

SIGN-RG02

end_date

Period end date

0..1

date
(1) (2) (3)

YYYY-MM-DDThh:mm:sszzzzzz

SIGN-RG01

SIGN-RG02

(1) By convention, the end_date data is excluded from the search, data from the Service's response.
(2) If the start_date has passed, then the end_date should be passed as a parameter.

(3) If start_date and end_date are given, they must be between 01/01/yyyy and 01/01/yyyy(+1), respectively.


NB:

– The Service’s field names are in English. Consult the paragraph on "Language – Field name translations" at the bottom of the page.
– Consult the section on "
Expected formats" for details of the parameters' expected formats.

 

Call examples:

Without parameters

URL:

GET /open_api/demand_response_signal/v1/demand_response_signals

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

With all parameters

URL:

GET /open_api/demand_response_signal/v1/demand_response_signals?start_date=2018-01-01T00:00:00%2B01:00&end_date=2019-01-01T00:00:00%2B01:00

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

 

 


 

4.1.1.3 Outputs

 

1..1

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start date for requested data

date

YYYY-MM-DDThh:mm:sszzzzzz

SIGN-RG01

SIGN-RG02

end_date

1..1

End date for requested data

date

YYYY-MM-DDThh:mm:sszzzzzz

SIGN-RG01

SIGN-RG02

signaled_dates

1..1

One value per signalled day. Table of values {JSON} structured as shown below:

 

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

start_date

1..1

Start date for which the signal is returned

date

YYYY-MM-DDThh:mm:sszzzzzz

end_date

1..1

End date for which the signal is returned

date

YYYY-MM-DDThh:mm:sszzzzzz

updated_date

1..1

Data update date

date

YYYY-MM-DDThh:mm:sszzzzzz

JSON return format:

 

GET /open_api/demand_response_signal/v1/demand_response_signals

{

 "start_date":"2018-01-01T00:00:00+01:00",

 "end_date":"2019-01-01T00:00:00+01:00",

 "signaled_dates":[

{

 "start_date":"2018-06-02T00:00:00+01:00",

 "end_date":"2018-06-02T00:00:00+01:00",

 "updated_date":"2018-06-02T00:00:00+01:00"

}

 ]

}

 

 

4.1.1.4 Control rules

 

Control rules for different input parameters:

 

Parameters

Description

Number

start_date

end_date

empty

empty

If no input parameter is given, the service automatically returns the signalling information for the current day and the next day.

SIGN-RG01

filled in

filled in

If the start_date and end_date parameters are given, the service returns the signals days for the year entered.

SIGN-RG02

 

Output control rules applied:

 

Number

Description

SIGN-RG03

The output data is ordered from the most recent start_date to the oldest.

SIGN-RG04

As the service's output, the data is returned as linked to calendar year.

 

4.1.1.5 Error codes

 

The following table lists the error codes which may be returned when the resource is called.

Details of these errors are described in chapter 5: Error details.

 

Error type

Error code

Details

Functional

DERESI_DEMAND_RESPONSE_SIGNALS_F01

§5.1.1

Functional

DERESI_DEMAND_RESPONSE_SIGNALS_F02

§5.1.1

Functional

DERESI_DEMAND_RESPONSE_SIGNALS_F03

§5.1.1

Technical

401

§5.2

Technical

403

§5.2

Technical

404

§5.2

Technical

408

§5.2

Technical

413

§5.2

Technical

414

§5.2

Technical

429

§5.2

Technical

500

§5.2

Technical

503

§5.2

Technical

509

§5.2

 

 

 

5         Details of errors

The diagram below shows the codes returned to the API's User depending on the sequencing of calls.

This paragraph details the generic errors that are common to all of the API's resources. As such, it does not describe request errors (HTTP 400 code). These errors are described resource by resource in the corresponding paragraph.

In the event of an error encountered during the authentication phase (while validating the username and password), an HTTP 401 “unauthorised" code is returned to the caller.

The second stage involves checking that the user has not exceeded the maximum number of calls authorised for the organisation. In the event of the number being exceeded, the caller is informed with an HTTP 429 code. In such cases, the response from the server will contain a "Retry-After:" header giving the time (in seconds) that the client will need to wait before resubmitting their request.

The third stage involves checking that the caller (identified by its OAuth2 token or its PKI certificate) has created an application on the Data Portal. Otherwise, the caller is informed by an HTTP 403 "forbidden"

The fourth stage involves checking that the API is associated with the application (subscription). Otherwise, the caller is informed by an HTTP 403 "forbidden" code.

The fifth stage involves accessing RTE’s resources. Various functional errors may occur. These are communicated to the User as JSON errors with an HTTP 400 code.

                                                                                                                                            

In the event of a technical incident occurring while processing the request at any of the stages, the caller will be informed by an HTTP 500 code.

 

 

 

JSON structure:

 

{

 "error": "short_name, error's explicit description",

 "error_description": "long name, readable by a user",

 "error_uri": "URI to the API user guide or the FAQ/documentation on the Data Portal"

 "error_details" : {

        "transaction_id" : "unique call identifier, useful in the event of an incident"

 }

}

 

·         The short description ("error") is a code which enables the calling application to automatically process error messages. It is represented by a series of words separated by “_”.

·         The long description ("error description") is a description enabling users to understand the source of the error more precisely. This name needs to be approved by the business line in order to confirm that it is explicit enough.

·         The URI to the user guide is present so as to provide more explanations depending on the API called.

·         The transaction_id field: provides a unique call identifier. This identifier can be communicated with RTE’s support services if there is an incident.

 

 


 

5.1     Functional errors 5.1.1   demand_response_signals

 

The table below lists the functional errors returned by the resource for an error in a request (HTTP 400 code):

 

DERESI_DEMAND_RESPONSE_SIGNALS _F01

Message

If one of the fields "start_date" or "end_date" is used, the two fields are mandatory. Please use either fields or neither.

Control Rule

If either of the start_date and end_date parameters are passed on their own, the Service generates this error.

Call example

GET /open_api/demand_response_signal/v1/demand_response_signals?start_date=2018-01-01T00:00:00%2B02:00

DERESI_DEMAND_RESPONSE_SIGNALS _F02

Message

If start_date and end_date are valued, start_date must be year-01-01 and end_date must be year(+1)-01-01.

Control Rule

start_date must be 01/01 and end_date must be 01/01 of the next year.

Call example

GET /open_api/demand_response_signal/v1/demand_response_signals?start_date=2018-06-01T00:00:00%2B02:00&end_date=2018-12-31T00:00:00%2B02:00

DERESI_DEMAND_RESPONSE_SIGNALS _F03

Message

One of the dates in the API input does not follow the format described in the user guide. Please verify compliance with the format for each field.

Control Rule

If one of the dates is not in compliance with the “YYYY-MM-DDThh:mm:sszzzzzz” format.

Call example

GET /open_api/demand_response_signal/v1/demand_response_signals?start_date=2018/01/01T00:00:00%2B02:00&end_date=2019/01/01T00:00:00%2B02:00

 


 

5.2     Technical errors

 

401

HTTP code

401

Message

Unauthorized

Description

Error generated when authentication has failed

403

HTTP code

403

Message

Forbidden

Description

Error generated if the caller is not authorised to call the resource

404

HTTP code

404

Message

Not Found

Call example

The resource called does not exist or no data was found

408

HTTP code

408

Message

Request Time-out

Call example

Error generated when there is no response from the service called or when the call to the service times out (http 408).

413

HTTP code

413

Message

Request Entity Too Large

Call example

The size of the request exceeds 5 MB

414

HTTP code

414

Message

Request-URI Too Long

Call example

The URI sent by the caller is longer than 512 characters.

429

HTTP code

429

Message

Too Many Requests

Call example

The maximum number of calls has been made in a given period of time.

500

HTTP code

500

Message

Internal Server Error

Call example

Any other technical error.

(This error is accompanied by a JSON message with an error_code and error_description field)

503

HTTP code

503

Message

Service Unavailable

Call example

Error generated during maintenance (HTTP 503).

509

HTTP code

509

Message

Bandwidth Limit Exceeded.

Call example

The total number of client requests has reached the maximum limit.