Experiment it live
The root (http://divaservices.unifr.ch/api/v2/) provides information about all available methods. The response will look as follows:
[
{
"name": "Otsu Binarization",
"description": "Otsu Binarization",
"type": "binarization",
"url": "http://divaservices.unifr.ch/api/v2/binarization/otsubinarization/1"
},
{
"name": "HOOSC Feature Extraction",
"description": "This code extracts Histogram of Orientation Shape Context (HOOSC) local shape descriptor from an input hieroglyph image.",
"type": "imageprocessing",
"url": "http://divaservices.unifr.ch/api/v2/imageprocessing/hooscfeatureextraction/1"
}
]
Each method is described in an object containing the following four data points:
name: The name of the methoddescription: A description of the methodtype: A classification of the type of the methodurl: The URL pointing to the endpoint for the methodProvides information about a specific information. The response looks as follows:
{
"general": {
"name": "Otsu Binarization",
"description": "Otsu Binarization",
"developer": "Marcel Würsch",
"affiliation": "University of Fribourg",
"email": "marcel.wuersch@unifr.ch",
"author": "Marcel Würsch",
"DOI": "10.1117/12.783598",
"type": "binarization",
"license": "Other",
"ownsCopyright": "1",
"expectedRuntime": 2.258397932816539,
"executions": 387
},
"input": [
{
"file": {
"name": "inputImage",
"description": "The input image to binarize",
"options": {
"required": true,
"mimeTypes": {
"allowed": [
"image/jpeg",
"image/png",
"image/tiff"
],
"default": "image/jpeg"
}
},
"userdefined": true
}
},
{
"outputFolder": {
"userdefined": false
}
}
],
"output": [
{
"file": {
"name": "otsuBinaryImage",
"type": "image",
"description": "Generated Binary Image",
"options": {
"mimeTypes": {
"allowed": [
"image/jpeg",
"image/png",
"image/tiff"
],
"default": "image/jpeg"
},
"colorspace": "binary",
"visualization": true
}
}
}
]
}
The JSON object is built of the following structure:
general: Contains general information about the method (e.g. author of the method, or DOI for referencing in scientific publications)input: A JSON array specifying the inputs required by the method.output: A JSON array specifiying the outputs generated by the method.The input and output array are further specified in the Tutorial on Inputs and Outputs
A POST request to the URL of a method starts the execution of a method.
The POST request needs to contain a request-body that contains all necessary data needed by the method.
Important: All POST request need to set the content-type to application/json. Otherwise they will be rejected by DIVAServices.
The request-body has the following structure:
{
"parameters":{},
"data":[
{
}
]
}
The parameter object will contain all regular parameter values, and the data array all input data related information. For mor information check out the tutorial on Inputs and Outputs.
The POST request will return an immediate response with the following structure:
{
"results": [
{
"resultLink": "http://divaservices.unifr.ch/api/v2/results/majorknowledgeableconey/data_0/data_0.json"
}
],
"statusCode": 202
}
The results array will contain an object with a resultLink for each data element that was used in the POST request. This resultLink URL will contain the actual result of the specific method call.
Since the requests are executed asynchronously, the client will have to poll for the results. As stated above, the client will receive a JSON response to the POST request that starts the execution of the method.
The response will either containt status: "planned" or status: "done" which can be used to identify whether or not the execution is finished.
The following Python and JavaScript functions serve as examples how polling can work:
Python
def pollResult(self, result_link):
""" Polls for the result of the execution in 1s intervals
Arguments:
result_link {string} -- [the resultLink generated by the POST request that started the execution]
Returns:
[json] -- [the result of the execution]
"""
response = json.loads(requests.request("GET", result_link).text)
while(response['status'] != 'done'):
if(response['status'] == 'error'):
sys.stderr.write('Error in executing the request. See the log file at: ' + response['output'][0]['file']['url'])
sys.exit()
time.sleep(1)
response = json.loads(requests.request("GET", result_link).text)
return response
JavaScript
/**
*
* Fetch the result from a given url
* Polls for the result every 1000ms (1s)
*
* */
function getResult(url) {
return new Promise(resolve => {
fetch(url, {
method: "GET"
}).then(function (res) {
return res.json();
}).then(function (data) {
if (data.status === "done") {
resolve(data);
} else {
setTimeout(function () {
resolve(getResult(url));
}, 1000);
}
})
})
}
The following request-bodycan be used to execute the Otsu Binarization on DIVAServices.
{
"parameters":{},
"data":[
{
"inputImage":"testCollection/ubb-A-II-0004_0002r.jpeg"
}
]
}
Provides a list of all existing collections. The returned JSON object is structured as follows:
{
"collections": [
{
"collection": {
"name": "irritatingflickeringpitbull",
"url": "http://divaservices.unifr.ch/api/v2/collections/irritatingflickeringpitbull"
}
},
{
"collection": {
"name": "dopeyscholarlykentrosaurus",
"url": "http://divaservices.unifr.ch/api/v2/collections/dopeyscholarlykentrosaurus"
}
}
]
Each collection has a name and an url under which more information can be fetched from.
Creates a new collection. The request-body to create a new collection has to look as follows:
{
"name": "ocr_models",
"files":[
{
"type":"url",
"value":"http://www.tmbdev.net/en-default.pyrnn.gz",
"name":"english.gz"
}
]
}
The following information needs to be provided:
name (optional): The identifier of this collection. If none provided a random one is generated.files: An array of files that should be added to this collection.Each entry of files is structured as follows:
type: the type of file that is provided, can be url or filevalue: The value for the file.name: The filename the filename should have within the collection (complete filename needed)The value depends on the type and the two following options are possible:
type=url: value points to the URL where the file can be downloaded fromtype=file: value is the base64 encrypted content of the fileNote: The complete request can not be larger than 250mb.
Provides detailed information about a collection. The returned JSON is structured as follows:
{
"statusCode": 200,
"statusMessage": "Collection is available",
"percentage": 100,
"totalFiles": 1,
"files": [
{
"file": {
"md5": "e816b16b11ee17a32ecaaf7b7a19b2c3",
"url": "http://divaservices.unifr.ch/api/v2/files/irritatingflickeringpitbull/original/inverseImage.jpg",
"identifier": "irritatingflickeringpitbull/inverseImage.jpg"
}
}
]
}
The files array contains a file object for each file that is in this collection.
The identifier can be used as data reference when executing a method.
Adds a file into a collection. The request-body needs to look as follows:
{
"files":[
{
"type":"url",
"value":"http://www.tmbdev.net/en-default.pyrnn.gz",
"name":"english.gz"
}
]
}
The same rules as in POST /collections apply here too.