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 besoin. Si la requête en 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 informatiosn 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édiaire 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.

 #!/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"
 
 tar -xf "${DATATYPE}_${FEEDER}_$DATE.xz"