DSaS API Documentation
The DSaS API is organized around REST. Our API is designed to have predictable, resource-oriented URLS, to use HTTP response codes to indicate API errors, and to use built-in HTTP features. JSON will be returned in all responses from the API, including errors.
Service
Class
com.datascience.gal.service.Service is a web-service container, binded to the
http://23.21.128.180:8080/GetAnotherLabel/rest url, could be runned locally on
[SERVER HOST:PORT]/GetAnotherLabel/rest.
Be aware that url is not correct till the right web-method [with parameter[s]] `s[`ve] been added, such as (please be familiar with Summary of Resource URL Patterns section) reset, exists, loadCategories e.g.
Brief Intro
To setup locally the project you may need Maven (3.x.x) (cmd mvn --version),
Tomcat 6, JRE/JDK(1.6, 6.x.0_x), MySQL.
MSQL is needed ONLY if you are suppose to use Web-Service named Service,
for other purposes of using DSaS you may be interested in reading How to run DSaS
What for do we need database? Which Pitfalls could we be faced with?
We need database to save to/load from by Id any data structure, such as
BatchDawidSkene/IncrementalDawidSkene, Category, various collections e.g.
Every web-method which contain id parameter always refers to the specific record of the table in database. Yes, right, ONE table, which gives a hand every entity, of any type, any time. Web-methods are NOT syncronized at the current stage of development. Table COULD contain duplicate data.
Which type of data is expected? How to test? In which order? Is it critical to keep some ordering of calling?
Usually id may not be only numeric, you may try any characters
Data should has JSON type, to generate
Category or
Collection of categories you may use
Composer Also you may try
cURL.
Web-methods are splitted by two groups, POST and GET oriented. To test GET methods you may just type in browser specific url, to test POST web-methods you may create simple html file with form.
Order of testing is important because you need to be sure that data which you treat exists.
Order of calling depends of previous executions. For instance every method name of which starts from
load (loadCategories, loadGoldLabels) stores/updates object BatchDawidSkene/IncrementalDawidSkene to/into the database. Afterwards any other web-method may use that object by specific id which you may keep in mind. None of the methods return list of objects, JFYI.
Libraries
Library available here, need to be built as .WAR and deployed on Tomcat 6.xx
API Endpoint
available here, just add web-method name and parameters
Summary of Resource URL Patterns
GET ping
DESCRITION
a simple method to see if the service is awake
PARAMETERS
none
SAMPLE REQUEST
http://23.21.128.180:8080/GetAnotherLabel/rest/ping
SAMPLE RESPONSE
"processing request at: 2012-03-27T22:06:06.619Z"
GET reset?id={id}
DESCRITION
resets the ds model
PARAMETERS
[any sequence of characters]
SAMPLE REQUEST
http://23.21.128.180:8080/GetAnotherLabel/rest/reset?id=1
SAMPLE RESPONSE
nullified the ds object, and deleted ds with id 1
GET exists?id={id}
DESCRITION
checks if BatchDawidSkene/IncrementalDawidSkene object with specified identefier exists in database (and cache)
PARAMETERS
[any sequence of characters]
SAMPLE REQUEST
http://23.21.128.180:8080/GetAnotherLabel/rest/exists?id=7
SAMPLE RESPONSE
true
POST loadCategories?categories={categories}&id={id}&incremental={incremental}
DESCRITION
load Categories and saves BatchDawidSkene/IncrementalDawidSkene object with specified identefier exists to the database (and cache)
PARAMETERS
[JSON Array]
[any sequence of characters]
[number]
SAMPLE REQUEST
[{"name":"name1","prior":-1.0,"misclassification_cost":{}},{"name":"name2","prior":-1.0,"misclassification_cost":{}}]
2
10
SAMPLE RESPONSE
built a ds with 2 categories[{"name":"name1","prior":0.0,"misclassification_cost":{"name1":0.0,"name2":1.0}},{"name":"name2","prior":0.0,"misclassification_cost":{"name1":1.0,"name2":0.0}}]
POST loadCosts?loadCosts={loadCosts}&id={id}
DESCRITION
Loads a json set of misclassification cost objects
PARAMETERS
[JSON Array]
[any sequence of characters]
SAMPLE REQUEST
[{"categoryFrom":"name1","categoryTo":"name2","cost":0.9},{"categoryFrom":"name1","categoryTo":"name2","cost":0.1},{"categoryFrom":"name2","categoryTo":"name1","cost":0.4}]
2
SAMPLE RESPONSE
adding 3 new misclassification costs
POST loadWorkerAssignedLabel?data={data}&id={id}
DESCRITION
add a worker-assigned label to the model
PARAMETERS
[JSON Object]
[any sequence of characters]
SAMPLE REQUEST
{"workerName":"workerName","objectName":"objectName","categoryName":"name1"}
2
SAMPLE RESPONSE
adding {"workerName":"workerName","objectName":"objectName","categoryName":"name1"}
POST loadWorkerAssignedLabels?data={data}&id={id}
DESCRITION
add a worker-assigned label to the model
PARAMETERS
[JSON Array]
[any sequence of characters]
SAMPLE REQUEST
[{"workerName":"workerName","objectName":"objectName","categoryName":"name1"},{"workerName":"workerName2","objectName":"objectName2","categoryName":"name2"}]
2
SAMPLE RESPONSE
adding 2 labels
POST loadGoldLabel?data={data}&id={id}
DESCRITION
add a gold label to the model
PARAMETERS
[JSON Object]
[any sequence of characters]
SAMPLE REQUEST
{"objectName":"objectName2","correctCategory":"name1"}
2
SAMPLE RESPONSE
adding gold label: {"objectName":"objectName2","correctCategory":"name1"}
POST loadGoldLabels?data={data}&id={id}
DESCRITION
add gold labels to the model
PARAMETERS
[JSON Array]
[any sequence of characters]
SAMPLE REQUEST
[{"objectName":"objectName2","correctCategory":"name1"}, {"objectName":"objectName","correctCategory":"name2"}]
2
SAMPLE RESPONSE
adding 2 gold labels
GET majorityVote?id={id}&objectName={objectName}
DESCRITION
computes majority votes for object
PARAMETERS
[any sequence of characters]
[any sequence of characters]
SAMPLE REQUEST
2
objectName2
SAMPLE RESPONSE
"name1"
POST majorityVotes?id={id}&objects={objects}
DESCRITION
computes majority votes for objects
PARAMETERS
[any sequence of characters]
[JSON Array]
SAMPLE REQUEST
2
[objectName,objectName2]
SAMPLE RESPONSE
{"objectName":"name2","objectName2":"name1"}
GET majorityVotes?id={id}
DESCRITION
computes majority votes for objects
PARAMETERS
[any sequence of characters]
SAMPLE REQUEST
2
SAMPLE RESPONSE
{"objectName":"name2","objectName2":"name1"}
POST objectProbs?id={id}&objects={objects}
DESCRITION
computes class probs objects
PARAMETERS
[any sequence of characters]
[JSON Array]
SAMPLE REQUEST
2
[objectName,objectName2]
SAMPLE RESPONSE
{"objectName2":{"name1":1.0,"name2":0.0},"objectName":{"name1":0.0,"name2":1.0}}
GET objectProb?id={id}&object={object}
DESCRITION
computes class probs objects
PARAMETERS
[any sequence of characters]
[JSON Object]
SAMPLE REQUEST
2
ObjectName2
SAMPLE RESPONSE
{"name1":1.0,"name2":0.0}
GET computeBlocking?iterations={iterations}&id={id}
DESCRITION
runs the algorithm, iterating the specified number of times
PARAMETERS
[number]
[any sequence of characters]
SAMPLE REQUEST
2
10
SAMPLE RESPONSE
performed ds iteration 10 times, took: 1ms.
GET printWorkerSummary?verbose={verbose}&id={id}
DESCRITION
print Worker`s info
PARAMETERS
[any sequence of characters]
[any sequence of characters]
SAMPLE REQUEST
no matter
2
SAMPLE RESPONSE
Worker: workerName
Error Rate: 46.0%
Quality (Expected): 41%
Quality (Optimized): 5%
Number of Annotations: 1
Number of Gold Tests: 1
Confusion Matrix:
P[name1->name1]=90.0%
P[name1->name2]=10.0%
P[name2->name1]=55.0%
P[name2->name2]=45.0%
Worker: workerName2
Error Rate: 19.0%
Quality (Expected): 42%
Quality (Optimized): 0%
Number of Annotations: 1
Number of Gold Tests: 1
Confusion Matrix:
P[name1->name1]=45.0% P[name1->name2]=55.0%
P[name2->name1]=10.0% P[name2->name2]=90.0%
GET printObjectsProbs?entropy={entropy}&id={id}
DESCRITION
calculates and prints object`s probabilities
PARAMETERS
[number with floating point]
[any sequence of characters]
SAMPLE REQUEST
2
0.5
SAMPLE RESPONSE
Object Pr[name1] Pr[name2] Pre-DS Majority Label Pre-DS Min Cost Label Post-DS Majority Label Post-DS Min Cost Label
GET objectProbs?object={object}&entropy={entropy}&id={id}
DESCRITION
calculates and prints object`s probabilities
PARAMETERS
[any sequence of characters]
[number with floating point]
[any sequence of characters]
SAMPLE REQUEST
ObjectName2
2
SAMPLE RESPONSE
null
GET printPriors?id={id}
DESCRITION
prints priors by given id
PARAMETERS
[any sequence of characters]
SAMPLE REQUEST
2
SAMPLE RESPONSE
Prior[name1]=0.5
Prior[name2]=0.5
GET classPriors?id={id}
DESCRITION
prints the list of the category/priority relations
PARAMETERS
[any sequence of characters]
SAMPLE REQUEST
2
SAMPLE RESPONSE
{"name1":0.5,"name2":0.5}
GET getDawidSkene?id={id}
DESCRITION
prints BatchDawidSkene or IncrementalDawidSkene by given identifier
PARAMETERS
[any sequence of characters]
SAMPLE REQUEST
2
SAMPLE RESPONSE
{"dsmethod":"UPDATEWORKERS","priorDenominator":2.0,"objects":{"objectName":{"name":"objectName","isGold":true,"correctCategory":"name2","categoryProbability":{"name1":0.0,"name2":1.0},"labels":[{"workerName":"workerName","objectName":"objectName","categoryName":"name1"}]},"objectName2":{"name":"objectName2","isGold":true,"correctCategory":"name1","categoryProbability":{"name1":1.0,"name2":0.0},"labels":[{"workerName":"workerName2","objectName":"objectName2","categoryName":"name2"}]}},"workers":{"workerName":{"name":"workerName","cm":{"categories":["name1","name2"],"matrix":{"{\"to\":\"name1\",\"from\":\"name2\"}":1.1,"{\"to\":\"name2\",\"from\":\"name1\"}":0.1,"{\"to\":\"name2\",\"from\":\"name2\"}":0.9,"{\"to\":\"name1\",\"from\":\"name1\"}":0.9},"rowDenominator":{"name1":0.9999999999999999,"name2":2.0}},"labels":[{"workerName":"workerName","objectName":"objectName","categoryName":"name1"}]},"workerName2":{"name":"workerName2","cm":{"categories":["name1","name2"],"matrix":{"{\"to\":\"name1\",\"from\":\"name2\"}":0.1,"{\"to\":\"name2\",\"from\":\"name1\"}":1.1,"{\"to\":\"name2\",\"from\":\"name2\"}":0.8999999999999999,"{\"to\":\"name1\",\"from\":\"name1\"}":0.9},"rowDenominator":{"name1":2.0,"name2":1.0}},"labels":[{"workerName":"workerName2","objectName":"objectName2","categoryName":"name2"}]}},"categories":{"name1":{"name":"name1","prior":1.0,"misclassification_cost":{"name1":0.0,"name2":0.1}},"name2":{"name":"name2","prior":1.0,"misclassification_cost":{"name1":0.4,"name2":0.0}}},"fixedPriors":false,"id":"2"}
EXAMPLE REQUEST
<form method="post" action="http://23.21.128.180:8080/GetAnotherLabel/rest/loadCategories" name="formOne" enctype="application/json; charset=utf-8">
<input name="id" value="2"/><input name="incremental" value="10"/>
<textarea name="categories">[{"name":"name1","prior":-1.0,"misclassification_cost":{}},{"name":"name2","prior":-1.0,"misclassification_cost":{}}]</textarea>
<button type="submit">Compute</button>
</form>