Modification de Usage de l'API

== Informations générales ==

L'API (Application Programming Interface) Poids-Plume permet d'accéder aux données en utilisant des outils informatiques, plutôt que via les visualisations proposées sur le site web. C'est le point d'entrée privilégié si vous souhaitez analyser les données du projet, ou encore télécharger les données de votre mangeoire. 

Pour utiliser l'API, il vous faut un compte à jour de son adhésion sur le site web Poids Plume, et une clé d'API ([https://data.poids-plume.fr/userinfo.php disponible sur votre compte utilisateur]). L'usage de l'API se fait dans le respect de ses conditions d'utilisation rappelées sur la page d'information pour un utilisateur. En plus de ces conditions d'utilisations, nous souhaiterions être un peu au courant de l'usage qu'en font les utilisateurs - n'hésitez-pas à nous communiquer toute utilisation que vous en faites, voire à présenter vos résultats à l'association ! Via la mailing liste par exemple ou lors des AGs.

== Informations techniques ==

Les informations accessibles via l'API Poids-Plume incluent les données issues des capteurs sur les mangeoires (poids, température, etc.), et les informations sur les vidéos des oiseaux (annotations, poids mesurée, etc.). Les vidéos elles-mêmes sont inaccessibles via ce service.

L'accès se fait via une requête '''POST''' sur l'adresse '''https://data.poids-plume.fr/data.php''', en renseignant les champs suivants dans la requête: 

* '''feeder''': la mangeoire pour laquelle les données sont à télécharger

* '''date''': la date pour laquelle télécharger les données (au format YYYY-MM-DD) 

* '''datatype''': le type de données à télécharger, 'rawdata', 'filtdata' ou 'visits', correspondant au données interpolées, filtrées et aux visites (voir la page d'information sur les [[Données_téléchargées]])

* '''username''': l'utilisateur faisant la requête (votre nom d'utilisateur) 

* '''sig''': Un HMAC sha-256 de votre requête et de votre clé d'API (voir code bash ci-dessous)

La code de réponse http de la page peut être 400 (Bad request) si les paramètres ci-dessus sont mal définis, 403 (Forbidden) si l'accès est refusé ou 404 si aucune donnée correspondante n'a été trouvée. Un message plus explicite expliquant pourquoi la requête a raté est renvoyé. Si la requête est bien formulée, un code de réponse 200 (OK) est renvoyé, et les données sont transférées au client. 

Concrètement, les données se présentent sous la forme d'un fichier '.xz' contenant des données tabulaires au format texte (les valeurs étant séparées par des tabulations, voir aussi les informations sur les [[Données_téléchargées|données téléchargées]]). Il faut extraire 
ce fichier (avec '''tar -xf''' par exemple), puis les données peuvent être (enfin) lues avec votre logiciel préféré. En pratique, on utilisera la plupart du temps des outils intermédiaires pour effectuer ce travail. 

=== Outils === 

==== Script bash minimal ==== 

Le script bash ci-dessous devrait pouvoir vous permettre d'effectuer une requête de données via l'API en téléchargeant des données pour une combinaison mangeoire/date/type de données. Il faut remplacer les champs '''API_USER''' et '''API_KEY''' par leurs valeurs (attention à ne pas faire fuiter ces informations publiquement !). Il peut servir également d'une implémentation de référence pour d'autres implémentations.

Attention, le script ne gère pas les erreurs (absence de données, mauvaise authentification, etc.), et n'extrait pas le fichier '.xz' téléchargé. Libre à vous de l'améliorer ! ;)

 #!/bin/bash
 # 
 # Minimal script to access data from the Poids-Plume project
 # 
 
 # User information 
 API_KEY="<key>"
 API_USER="<user>"
 
 # Information on request
 FEEDER="carduelis"
 DATE="2020-12-20"
 DATATYPE="rawdata"
 
 # Compute hmac
 SIG="$(echo -n "${FEEDER}${DATE}${DATATYPE}${API_USER}" | \
          openssl sha256 -hmac "$API_KEY" | \
          cut -d"=" -f2 | 
          sed "s/ //g")"
 
 # Make request
 curl -X POST \
   -d "feeder=$FEEDER" \
   -d "date=$DATE" \
   -d "datatype=$DATATYPE" \
   -d "username=$API_USER" \
   -d "sig=$SIG" \
   --output "${DATATYPE}_${FEEDER}_$DATE.xz" \
   "https://data.poids-plume.fr/data.php"

==== Paquet R pour l'API Poids-Plume ====

Un [https://gitlab.com/poidsplume/poidsplumer paquet R] est disponible pour utiliser l'API Poids-Plume. Si vous utilisez R, vous pourrez alors charger les données dans votre environnement de travail. 

L'installation du paquet se fait via '''devtools''': 

 install.packages("devtools") 
 devtools::install_git("https://gitlab.com/poidsplume/poidsplumer")

Vous pouvez ensuite charger le paquet et utiliser ses fonctionnalités. La fonction principale qui vous intéressera le plus probablement est la fonction '''get_data()''', qui prend en argument la mangeoire, la date (format YYYY-MM-DD) et le type de données demandé, et qui charge les données correspondantes dans votre environnement de travail. Il faut au préalable que vous renseigniez votre nom d'utilisateur et votre clé d'API. Un petit exemple minimal serait le suivant: 

 library(poidsplumer) # On charge le paquet d'accès aux données
 pplume_api_set(user = <user>, key = <key>) # Remplacez par vos informations 
 
 # On fait la requête. my_data est un data.frame qui contient les données correspondantes (ou NULL si aucune données n'a pu être téléchargée)
 my_data <- get_data("carduelis", "2020-12-20", "rawdata")

A noter que vous pouvez aussi charger votre nom d'utilisateur et votre clé d'API à partir d'un fichier externe, en utilisant '''pplume_api_set_from_file(<file>)'''. Cela vous permettra de partager le code de vos analyses sans risque de faire fuiter vos informations secrètes !

La fonction '''get_data()''' utilise un cache pour ne pas télécharger plusieurs fois les mêmes données depuis le serveur web - merci d'en profiter afin de diminuer la charge du serveur ;)

Les quelques fonctions du paquet R sont documentées (voir par exemple '''?get_data'''). Un exemple de fichier Rmarkdown est également installée avec le paquet. Vous pouvez obtenir son chemin d'accès sur votre ordinateur à l'aide de la commande suivante: 

 file.path(path.package("poidsplumer"), "inst", "doc", "api_example.Rmd")