Create variables for a site

Presentation

Description Authorization Method Query
This query allows you to create new variables for a site by sending a TSV file, which must follow a specific format. -form. Required by Basic HTTP (username and password). POST /v1/users/:userID/sites/:siteID/variables

URL parameter

Parameter Type Description
:userID String Unique identifier of the user If you do not know your username, you can use the keyword "current" instead.
:siteID String Unique identifier of the site.

Query parameter

Required

Parameter Type Descriptio
metadata File List of variables and their metadata This file will be in the TSV format detailed below.
Format

The metadata file must be written in a format that the server understands, so it should contain a file declaration header, the column names of the file, and the list of variables and their metadata The separator used is the tab (make sure that you use tabs and not spaces.) Here is an example of a well-formatted file :

            FORMAT_VERSION  1
            CREATION_DATE   2014-02-13T14:22:07Z
            ID_SITE test_site
            FEEDBACK_TO me@worldcompany.com

            varname label   type    value_type  units   lower_bound upper_bound delta_min   delta_max
            energy_aircond_3    aircond_3   energy  N   kWh
            energy_aircond_1    aircond_1   energy  N   kWh
            energy_aircond_2    aircond_2   energy  N   kWh
            energy_plugs_2  plugs_2 energy  N   kWh
            energy_plugs_3  plugs_3 energy  N   kWh
            energy_lights_3 lights_3    energy  N   kWh
            energy_plugs_1  plugs_1 energy  N   kWh
            energy_lights_1 lights_1    energy  N   kWh
            energy_lights_2 lights_2    energy  N   kWh
            

In our previous example :

FORMAT_VERSION Version of the file format used. Currently, we are using version 1.
CREATION_DATE Date created file.
ID_SITE Identifier of your site.
FEEDBACK_TO E-mail address of the person in charge of the site who will be notified of the creation of the data.
varname Unique identifier of the variable.
label Label used to name the variable in a text space, for example.
type Type of the variable (energy, temperature, ...).
value_type Type of data received (N for digital, L for logic, T for text).
units Unit of variable.
lower_bound (optional) Lower limit inclusive of allowable values.
upper_bound (optional) Upper limit inclusive of allowable values.
delta_min (optional) Minimum differential inclusive with previous value.
delta_max (optional) Maximum differential inclusive with previous value.

Optional

None.

Successful message

Sample Query

            curl -i -X POST 'https://api.openrj.eu/v1/users/current/sites/test_site/variables' -u cstb_test:cstb2014 -F metadata=@test_site_metadata.csv

            201 CREATED

            {
                "message": "Metadata transfered with success."
            }
            

Error message "Bad file format: missing ..."

Sample Query

            curl -i -X POST 'https://api.openrj.eu/v1/users/current/sites/test_site/variables' -u cstb_test:cstb2014 -F metadata=@invalid_metadata.tsv

            400 BAD REQUEST

            {
                "error": "Missing FORMAT_VERSION in line 1"
            }
            

Causes

The file sent is incorrectly formatted, missing an element, please refer to the error message and description of the format to correct your file and return it.

Error message"Bad file format: missing ..."

Sample query

            curl -i -X POST 'https://api.openrj.eu/v1/users/current/sites/test_site/variables' -u cstb_test:cstb2014

            400 BAD REQUEST

            {
                "error": "Missing metadata file."
            }
            

Causes

You forgot to attach the metadata file to the REST request, make sure you send it as a file attached to the query and not as "query string" or in the "Body of query."

Missing "authorization headers"

Sample query

            curl -i -X POST 'https://api.openrj.eu/v1/users/current/sites/test_site/variables'

            400 BAD REQUEST

            {
                "error": "Missing authorization headers"
            }
            

Causes

You forgot the "username" "password" parameters required for authentication in your query.

Error message "Unauthorized"

Sample query

            curl -i -X POST 'https://api.openrj.eu/v1/users/current/sites/test_site/variables' -u rtyui:ertyui

            401 Unauthorized

            {
                "error": "Unauthorized"
            }
            

Causes

You have misidentified or you do not have access to this information.

Error message " Site not found "

Sample query

            curl -i -X POST 'https://api.openrj.eu/v1/users/current/sites/test_sit/variables' -u rtyui:ertyui

            404 Not Found

            {
                "error":"Site not found."
            }
            

Causes

This site does not exist.