====== MKey WebServices Details ======

===== Webservice function : =====
The Mkey+ webservice provides 7 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:** 

   1. /identification/getDescriptiveData
   2. /identification/getRemainingItemsAndDescriptorsUsingIDs
   3. /identification/getDescription
   4. /identification/removeSDD
   5. /identification/changeDescriptionHistory
(BETA)
   6. /identification/getSimilarityMap
   7. /identification/getSimilarityMapForRemainingItem
	
For instance, the URL to call the first function is : http://mkey.services.identificationkey.fr/identification/getDescriptiveData

These functions return Json objects, and each element returned has a specific name (see Development API).


===== Performing an Interactive Identification using Mkey+ and a custom client =====
**Development API**

The parameters in entry of the Mkey+ API functions only use the stringified*
version of the Mkey+ JSON objects.

The webservice listen to GET query methods and the dataType must be Jsonp.

Here is an example of a JQuery javascript code snippet that calls one of MKey+ function: 
<code>var webserviceURL = http://mkey.services.identificationkey.fr
  var sddFileURL = http://yourServer.com/yourSddFile.xml
  $.ajax({
	  url : webserviceURL + '/identification/getDescriptiveData',
	  data : {
		      sddURL : sddFileURL,
		      withGlobalWeigth : true
			 },
	method : 'GET',
	dataType : 'jsonp'

  }).done(function(data) {
 	… response management …
  }
</code>

  * using the standard javascript function JSON.stringify()


===== 0. Basic Json objects used and returned by Mkey+ =====
**Item:** This object represents an item which can be described in a knowledge base.
For taxonomists, it usually is a taxon.
<code>{
	name : String, an item's name
	alternativeName : String, an item's alternative name
	detail : String, an item's detailed description
	resourceIds : [long], the IDs of the resources associated to an item
	id : long, an item's id, unique identifier generated sequentially by Mkey+
} </code>

**Descriptor:** This object is a tool that serves to describe Items, essentialy a 
Character for taxonomists. A Descriptor can be described with States (if it is a
categorical Descriptor), or a Quantitative Measure (If it is a quantitative
Descriptor).
<code>{
	name : String, a Descriptor's name
	detail : String, a Descriptor's detailed description
	resourceIds : [long], the IDs of the resources associated to a Descriptor
	stateIds : [long], the IDs of the states associated to a Descriptor
	inapplicableState = [long], the states of a parent Descriptor
						for which a Descriptor is inapplicable
	isCategoricalType = Boolean, true if the Descriptor is a categorical
						Descriptor, false otherwise
	isQuantitativeType = Boolean, true if the Descriptor is a quantitative
						Descriptor, false otherwise
	isCalculatedType = Boolean, true if the Descriptor is a calculated
						Descriptor, false otherwise
	id : long, this Descriptor's id, an unique identifier generated sequentially 
	by Mkey+
}</code>

**State**: this object is a component of categorical Descriptors, e.g. for a 
Descriptor named "Color of the eye", its States could be "Blue", "Black", etc...
<code>{
	name : String, a state's name
	detail : String, a state's detailed description
	resourceIds : [long], the IDs of the resources associated to a state
	id : long, a state's id, an unique identifier generated sequentially by Mkey+
}</code>

**Resource**: this object is a storage object, and is used to store media resources,
which can be associated to several objects, such as Items, Descriptors, States, 
etc...
<code>{
	name : String, a resource's name
	author : String, a resource's author
	type : String, a resource's media type ("video","image","sound")
	url : String, a resource's url
	legend : String, a resource's legend
	keywords : String, a resource's keywords
	id : long, a resource's id, an unique identifier generated sequentially by 
	Mkey+
}</code>

**DescriptionElement**: This object stores the description of an Item, according to 
a single Descriptor, it represents the content of a single cell of the taxa / 
characters matrix. It may contain the list of selected States if the Descriptor 
is a categorical Descriptor, or a QuantitativeMeasure object, if the Descriptor 
is a quantitative Descriptor.
<code>{
	calculatedStates : [state], the calculated states representing an item's 
			   description
	contextualWeight : int, the weigth of this description element
	quantitativeMeasure : quantitativeMeasure, the quantitative measure re-
                              -prensenting an item description
	states : [state], the states representing an item's description
	unknown : boolean, true if this description element is unkwnow
}</code>

**QuantitativeMeasure**: This object is associated to a DescriptionElement object,
for a given quantitative Descriptor and Item, it contains the quantitative 
measures used to describe a specific Item for a given quantitative Descriptor.
<code>{
	min : long, this QuantitativeMeasure's minimum value
	max : long, this QuantitativeMeasure's maximum
	mean : long, this QuantitativeMeasure's mean
}</code>

===== 1. Service : getDescriptiveData =====
First function to be called, //getDescriptiveData initializes the webservice// both
on the client and server side. It returns every element used in the
identification process, parsed from the SDD file.

**path :** /identification/getDescriptiveData(String SDDurl, Boolean withGlobalWeigth)

**parameter** (in the javascript before stringify):
<code>* SDDurl = String
* withGlobalWeigth = Boolean
</code>

**returns** :
<code>{descriptorsScoreMap,Items,Descriptors,States,Resources,DescriptorRootId,Depend-
-ancyTable,InverteddependencyTable}</code>


  * Items = [item], every item contained in the SDD
  * Descriptors = [Descriptor], every Descriptor contained in the SDD
  * States = [state], every states contained in the SDD
  * Resources = [resource], every resources contained in the SDD
  * descriptorsScoreMap = {Descriptor,float}, an associative map, which associates
	to each Descriptor its discriminant power.
  * DescriptorRootId = [int], ids of the node roots ( no dependency)
  * InvertedDependencyTable = {long,long}, the first long is the ID of the descriptor which parent is the second long.

===== 2. Service : getJSONRemainingItemsAndRemainingDescriptorsScoreUsingIds =====
Main function, used to retrieve the remaining (i.e. non-discarded) Items based
on a submitted description. It also returns the remaining Descriptors, along 
with their new discriminant power.

**path** : 
/identification/getJSONRemainingItemsAndRemainingDescriptorsScoreUsingIds(String
SDDurl, String descriptions, String remainingItemsIDs, String discardedDescrip-
-torsIDs, Boolean withScoreMap, Boolean withGlobalWeigth)

**parameter** (in the javascript before stringify):

<code>SDDurl = String
description = {
	selectedStatesNames : [int]
	quantitativeMeasure : {min=int,max=int,mean=int}	
}
remainingItemsID = [int]
discardedDescriptorsID = [int]
withScoreMap = boolean
withGlobalWeigth = boolean
</code>

**returns** :
<code>{discardedDescriptorsInIteration,remainingItems,descriptorScoreMap}</code>

  * remainingItems = [[item]], array of remaining items
  * discardedDescriptorsInIteration = [[Descriptor]], array of discarded descriptor, child descriptor can be discarded with its parents.
  * descriptorsScoreMap = {Descriptor,float}, an associative map, which associates to each Descriptor its discriminant power.


===== 3. Service : getDescription =====
Returns the description (i.e. the description of all the Descriptors) for an
Item whose name has been passed as an argument.
Used to display the item description window.

**path** : /identification/getDescription(String itemName, String SDDurl)

**parameter** (in the javascript before stringify):
  * itemName : String
  * SDDurl : String

**returns** :
<code>{description,innapDescriptorId}</code>

  * description = [descriptionElement], array of description elements describing this item.
  * innapDescriptorId = [int], array of inapplicable descriptor IDs


===== 4. Service : removeSDD =====
Delete the sdd from the Mkey+ server memory.

**path** : /identification/removeSDD(String SDDurl)

**parameter** (in the javascript before stringify):
  * SDDurl : String

**returns** :
<code>nothing</code>

===== 5. Service : changeDescriptionHistory =====
Compute identification based on the description given in parameter. This function is used to modify at all time user's identification.

**path** : /identification/changeDescriptionHistory

**parameter** (in the javascript before stringify):
  * SDDurl : String
  * descriptions : [{selectedStatesNames : [int], quantitativeMeasure : {min=int,max=int,mean=int}}]

**returns** :
<code>{discardedDescriptors,remainingItems,descriptorScoreMap,descriptions}</code>

  * remainingItems = [[item]], array of remaining items
  * discardedDescriptorsInIteration = [[Descriptor]], array of discarded descriptor, child descriptor can be discarded with its parents.
  * descriptorsScoreMap = {Descriptor,float}, an associative map, which associates to each Descriptor its discriminant power.
  * descriptions = [{selectedStatesNames: [int],quantitativeMeasure : {min=int,max=int,mean=int}}], the new description computed by the function.

===== 6. Service : getSimilarityMap =====
Return a map which link items with a float representing a similarity score.
This score is computed base on the descriptions submitted by the user. Items
which have few difference with the descriptions given in parameter will have a 
high score.

**path :** /identification/getSimilarityMap

**returns** : {similarityMap}

  * similarityMap = [int,float], int is the item ID and float the corresponding similarity score.

===== 7. Service : getSimilarityMapForRemainingItem =====
Return a map which link items with a float representing a similarity score.
This score is computed base on a global description regrouping every remaining 
items description elements. Items which have few difference with the descrip-
tions given in parameter will have a high score.

**path :** /identification/getSimilarityMapForRemainingItem

**returns** : {similarityMap}

  * similarityMap = [int,float], int is the item ID and float the corresponding similarity score.