====== Xperience WebServices Details ======

===== Xperience Webservice function : =====
The Xperience webservice provides 6 functions. These functions can be queried using HTTP requests. They can be reached using URLs created with the webservice address (http://mkey.services.identificationkey.fr) and a path to a webservice function. The seven functions are:

<code> 
 1. /xperience/addrecord
 2. /xperience/getrecord
 3. /xperience/getallitems
 4. /xperience/getfeedbackscsv
 5. /xperience/validate
 6. /xperience/updatesddurl
</code>

For instance, the URL to call the first function is: http://mkey.services.identificationkey.fr/xperience/addrecord.
These functions return Json objects, and each element returned has a specific name (see Development API). 

=====1. addrecord =====
Send a new record of an identification process with xperience mod

**path :** /xperience/addrecord

**parameter** :

  * String sddVersion => name of the sdd file used for this identification (ex : 20150113-135241.sdd.xml )
  * String sessionid => sessionid with the form : BASEID-WHATEVER (ex : 1916916151212-123SDAD32132 )
  * String jsonItemsSelectedmkeyid => json with the items given by the user (ex : [123,43] )
  * String urlImageUser => (facultatif)

**returns** : 
<code>{ 'status' : 'ok' , 'message' : // , 'spipollsessionid' : 'XXXX-YYYYY' }</code>

**error example :** 
<code>{ 'status' : 'Error' , 'message' : 'Xperiense Data Base not found' ,'spipollsessionid' : 'XXXX-YYYYY' }</code>

=====2. getrecord =====
get a history entry

**path :** /xperience/getrecord

**parameter** :

  * String sessionid => sessionid with the form : BASEID-WHATEVER (ex : 1916916151212-123SDAD32132)

**returns** :
feed the json return with the list of taxa given by the user
<code>{ "status" : "ok" , "value" : {"urlimage":"none","items":["979","1077"],"sessionid":"0123456789-id666"} }</code>

**error example :**
<code>{ "status" : "error" , "value" : {"message":"Record not found","sessionid":"0123456789-id66"} }</code>


===== 3. getallitems =====
Get list of items in map : Name -> Uniqueid

**path :** /xperience/getallitems

**parameter** :
  * String sessionid => sessionid with the form : BASEID-WHATEVER (ex : 1916916151212-123SDAD32132)

**returns** :
<code>{ "status" : "ok" , "value" : {"items":{"Les Sphinx du Pin et mauresque (<i>Sphinx maurorum<\/i>, <i>Sphinx pinastri<\/i>)":"1031","Les Clairons brillants (<i>Korynetes<\/i> et autres)":"812","L'Ecaille marbrée (<i>Callimorpha dominula<\/i>)":"402"},"sessionid":"0123456789-id666"} }</code>

**error example :** 
<code>{ "status" : "error" , "value" : {"message":"Record not found","sessionid":"0123456789-id66"} }</code>


===== 4. getfeedbackscsv =====
Get all feedback as CSV in a json return

**path :** /xperience/getfeedbackscsv

**parameter** :
  * String baseid => id of the base (ex : 1916916151212)

**returns** :
<code>{ 'status' : 'ok' , 'value' : 'LES MATRICES' }</code>

**error example :** 
<code>{ "status":"error" ,"value":{"message":"Xperience Base not found", "baseid":"0123456789"} }</code>

**LES MATRICES :**

  * TaxaNames (metadata) : Liste des identifiants des items avec leurs noms
  * DescriptorsNames (metadata) : Liste des identifiants des descripteurs avec leurs noms
  * StatesNames (metadata) : Liste des identifiants des états avec leurs noms
  * TaxaConfusion : Une seule matrice de confusion des taxons
  * TaxaDescriptor : Une seule matrice avec en rangé les items et en colonne les descripteurs. Pour chaque descritpeurs, quatres colonnes : nombre d'utilisation, nombre d'erreurs, nombre de doute, nombre d'erreur apres un doute
  * StatesConfusionByDescriptor : Un matrice confusion entre les états par descripteur. Avant chaque matrice un ligne avec “DescIDDESCRIPTEUR” (ex : Desc12)
  * StatesConfusionByDescriptor : Un matrice confusion entre les états par descripteur et par items. Avant chaque matrice un ligne avec “TaxonIDTAXON;DescIDDESCRIPTEUR” (ex : Taxon43;Desc12)


===== 5. validate =====
Validate a identification process record

**path :** /xperience/validate

**parameter** :
  * String item => uniqueid of the item that will be used for the validation ((ex : 32)
  * String sessionid => sessionid with the form : BASEID-WHATEVER (ex : 1916916151212-123SDAD32132)


**returns** :
<code>{ "status" : "ok" , "value" : {"message":"record validated","sessionid":"0123456789-id666","taxon":"371"} }</code>

**En cas de taxon non trouvé, on renvoie la liste des taxons possibles, dans “items” :**
<code>{ "status" : "notfound" , "value" : {"items":{"Les Sphinx du Pin et mauresque (<i>Sphinx maurorum<\/i>, <i>Sphinx pinastri<\/i>)":"1031"},"sessionid":"0123456789-id666","taxon":"1213"} }</code>

**error example :** 
<code>{ "status" : "error" , "value" : {"message":"Record not found","sessionid":"0123456789-id1","taxon":"1213"} }</code>

===== 6. updatesddurl =====
Update Sdd Url

**path :** /xperience/updatesddurl

**parameter** :
  * String baseid => baseid : id of the base (ex : 1916916151212)
  * String sddurl => the news sdd url. See the sddmanger (ex: http://nomdomain.com/messdd/

**returns** :
<code>{ 'status' : 'ok' , 'message' : // }</code>

**En cas de taxon non trouvé, on renvoie la liste des taxons possibles, dans “items” :**
<code>{ 'status' : 'error' , 'message' : 'Xperience Base not found' }</code>

**error example :** 
<code>{ "status" : "error" , "value" : {"message":"Record not found","sessionid":"0123456789-id1","taxon":"1213"} }</code>