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)<br />

 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:

0@@

• using the standard javascript function JSON.stringify()

Item: This object represents an item which can be described in a knowledge base. For taxonomists, it usually is a taxon.

1@@

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).

2@@

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…

3@@

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…

4@@

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.

5@@

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.

6@@

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):

7@@

returns :

8@@

• 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 descrip-

1. tor which parent is the second long.

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):

9@@

returns :

10@@

• 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.

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 :

11@@

• description = descriptionElement, array of description elements describing

this item.

• innapDescriptorId = int, array of inapplicable descriptor IDs

Delete the sdd from the Mkey+ server memory.

path : /identification/removeSDD(String SDDurl)

parameter (in the javascript before stringify):

• SDDurl : String

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):

• SDDurl : String
• descriptions : selectedStatesNames : [int,

quantitativeMeasure : {min=int,max=int,mean=int}

         }]

returns :

12@@

• 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 = : [int,

quantitativeMeasure : {min=int,max=int,mean=int}

       }], the new description computed by the function.

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.

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.

/identification/getSimilarityMapForRemainingItem

returns : {similarityMap}

• similarityMap = int,float, int is the item ID and float the corresponding similarity score.