API
Make sure you have added thing as explained in the section: Adding thing and creating the required settings.
Generality
This part concerns the use of the API in the thing code.
- The base url that is used by the different API routes is: YoupiLab IoT. You can store it in a global variable for example in Arduino:
- You needed your APP_ID and your APP_KEY Who serves unique identifier and thing identification key respectively. You can them also store in global variables, for example in Arduino:
const String BASE_URL = "https://iot.youpilab.com/api";
const String APP_ID = "<Votre_APP_ID>";
const String APP_KEY = "<Votre_APP_KEY>";
Retrieve information
You can have the information about your thing by entering the following url
https://iot.youpilab.com/api/data/ping?APP_ID=<Votre_APP_ID>&APP_KEY=<Votre_APP_KEY>
And you will receive a json which provides information on the creation date of the thing, the owner, the credentials, the last login a bit like this:
{
"status": "success",
"message": "Thing connected",
"user": {
"id": <id>,
"unique_id": "<unique_id>",
"name": "<nom_utilisateur>",
"email": "<votre_mail>",
"role": "user",
"confirmation_token": null,
"subscription_unique_id": "b267bc81351c3315e8d6c867551b9fc6",
"created_at": "2021-06-14 12:48:53",
"updated_at": "2021-07-27 05:19:02",
"last_sign_in": "2021-07-27 05:19:02"
}
}
Send data
Assuming you had (undefined) parameters, the url to use is
https://iot.youpilab.com/api/data/send?APP_ID=<Votre_APP_ID>&APP_KEY=<Votre_APP_KEY>&<nom_param_1>=<valeur_param_1>&<nom_param_2>=<valeur_param_2>&<nom_param_3>=<valeur_param_3>...
where you fill in the different fields surrounded by chevrons.
If the sending of the data was successful you will have the following json return:
{
"status": "success",
"message": "Data successfully saved"
}
in addition to an HTTP-200 response.
Example
Here is an example in Arduino of sending data on our platform where we had created two settings: - nom - age
const String BASE_URL = "https://iot.youpilab.com/api";
const String APP_ID = "id_equipement_ajoute";
const String APP_KEY = "1a2b3c4d5e";
String post_url = BASE_URL + "/data/send?" +
"APP_ID=" + APP_ID +
"&APP_KEY=" + APP_KEY +
"&nom=" + "YoupiLab" +
"&age=" + 10;
Which equals
String post_url = "https://iot.youpilab.com/api/data/send?APP_ID=id_equipement_ajoute&APP_KEY=1a2b3c4d5e&nom=YoupiLab&age=10"
Usually the values of the data to be sent (name, age for example) change according to the execution of the program, you can then use variables instead of the values entered in the url.
Types of data
We have 5 Types
- Integger
- Boolean
- String
- Dooble
- Any
So when adding a parameter you should specify its type. The Any type is reserved for subscribers who have existing projects. From now on, for your future projects, it is recommended to type your variables.
If sending typed data contains an error here is the following json token:
{
"status": "Parameter type not respected",
"message": "Parameter type not respected integer type is required"
}
in addition to an HTTP-500 response.
Count the number of data
You can also count the number of data sent to the platform iot.youpilab.com from your thing by entering this url
https://iot.youpilab.com/api/data/count?APP_ID=<Votre_APP_ID>&APP_KEY=<Votre_APP_KEY>
This then returns you a number, for example
35
indicating the number of entries/data already sent to the platform using the identifiers of the thing.
Retrieve data
https://iot.youpilab.com/api/data/pull?APP_ID=<Votre_APP_ID>&APP_KEY=<Votre_APP_KEY>&start=<debut_donnees>&end=<fin_donnees>
This will then return you a json similar to this using the data (id, key) from the example given above:
{
"status": "success",
"message": "Data has been successfully recovered.",
"parameters_count": 2,
"parameters": [
"nom",
"age"
],
"data_count": 2,
"data": [
[
{
"id": 3509,
"param_unique_id": "<id_des_params>",
"device_unique_id": "id_equipement_ajoute",
"value": "YoupiLab",
"unit": "n\/a",
"deleted": 0,
"created_at": "2021-07-26 17:26:38",
"updated_at": "2021-07-26 17:26:38"
}
],
[
{
"id": 3510,
"param_unique_id": "<id_des_params>",
"device_unique_id": "id_equipement_ajoute",
"value": "10",
"unit": "n\/a",
"deleted": 0,
"created_at": "2021-07-26 17:26:38",
"updated_at": "2021-07-26 17:26:38"
}
]
]
}
Here in the url we had passed the value 1 to both parameters
start plus
end to indicate the indices actually reading the data in
considering any data sent to the platform as an array.
Execute an action
You can then retrieve pending actions or tasks to perform using this url:
https://iot.youpilab.com/api/controls/get?APP_ID=<Votre_APP_ID>&APP_KEY=<Votre_APP_KEY>
You then get an array of tasks to perform as a response.
Like this answer
0 : 0
Send a feedback
Once an action is executed you can also send feedback to confirm its execution and therefore next time this action will no longer be recovered
https://iot.youpilab.com/api/controls/executed?APP_ID=<Votre_APP_ID>&APP_KEY=<Votre_APP_KEY>
Execute terminal task
You can execute a task you have written in the terminal thing using this url :
https://iot.youpilab.com/api/terminal/?TERM=<TERMINAL_ID>
You then get a response like this.
{
"success": true,
"TERMINAL": "id_of_terminal",
"TASK_ID": "id_task_executed"
}
https://iot.youpilab.com/api/terminal/response/?TERM=<TERMINAL_ID>&TASK_ID=<TERMINAL_TASK_ID>&RESP=<RESPONSE_OF_EXECUTION>The following response will be returned and the one of execution task of terminal will be displayed in terminal of thing
{
"success": true,
"message": "Response has been send successfully",
}