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).
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:
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 …
}
Item: This object represents an item which can be described in a knowledge base. For taxonomists, it usually is a taxon.
{
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+
}
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).
{
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+
}
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…
{
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+
}
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…
{
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+
}
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.
{
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
}
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.
{
min : long, this QuantitativeMeasure's minimum value
max : long, this QuantitativeMeasure's maximum
mean : long, this QuantitativeMeasure's mean
}
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):
* SDDurl = String * withGlobalWeigth = Boolean
returns :
{descriptorsScoreMap,Items,Descriptors,States,Resources,DescriptorRootId,Depend-
-ancyTable,InverteddependencyTable}
to each Descriptor its discriminant power.
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):
SDDurl = String
description = {
selectedStatesNames : [int]
quantitativeMeasure : {min=int,max=int,mean=int}
}
remainingItemsID = [int]
discardedDescriptorsID = [int]
withScoreMap = boolean
withGlobalWeigth = boolean
returns :
{discardedDescriptorsInIteration,remainingItems,descriptorScoreMap}
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):
returns :
{description,innapDescriptorId}
Delete the sdd from the Mkey+ server memory.
path : /identification/removeSDD(String SDDurl)
parameter (in the javascript before stringify):
returns :
nothing
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):
returns :
{discardedDescriptors,remainingItems,descriptorScoreMap,descriptions}
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}
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}