Skip to content

Communication

Jump to bottom Edit New page
Marcel Würsch edited this page Apr 25, 2017 · 15 revisions

Communication

In this part we explain how communication with DIVAServices is performed, what routes are available in general and how to interact with DIVAServices.

Introduction

DIVAServices is a RESTFul Web Service, this means all communcation is performed using standard HTTP request (in our case mainly GET and POST requests).

If you are only interested in a technical overview of the available routes you can access the OpenAPI configuration file available here: swagger.json. For a visualization of the OpenAPI documentation please use the SwaggerUI and "Explore" the raw content of of the swagger.json file

In the following subchapters we explain the different default routes that are available.

Getting Information

All existing information can be received using HTTP GET requests. The following default routes are available

Root information

/

Provides an overview of all available methods. The entries follow the following JSON-Schema: conf/schemas/generalAlgorithmSchema.json

Example Response

[
  {
    "name": "Text Block Extraction",
    "description": "Text block extraction method",
    "type": "layout analysis",
    "url": "http://divaservices.unifr.ch/api/v2/extraction/textblock/1"
  },
  {
    "name": "Multi Scale Interest Point Detection",
    "description": "Multi scale interest point detectors based on Gaussian scale space",
    "type": "interest points",
    "url": "http://divaservices.unifr.ch/api/v2/ipd/multiscale/1"
  },
  {
    "name": "kraken binarization",
    "description": "Binarization from the kraken package",
    "type": "binarization",
    "url": "http://divaservices.unifr.ch/api/v2/binarization/krakenbinarization/1"
  }
]

Method information

To access detailed information about a method create a GET request to the specific url (e.g. http://divaservices.unifr.ch/binarization/krakenbinarization/1). This will return a JSON object of the detailed information:

Example Response

{
  "general": {
    "name": "seam carving text line extraction",
    "description": "Text Line Segmentation using Seam Carving",
    "developer": "Developer Name",
    "affiliation": "University",
    "email": "EMail",
    "author": "Author Name",
    "website": "http://ivrl.epfl.ch/research/handwriting_recognition/text_line_extraction",
    "DOI": "10.1109/ICFHR.2014.127",
    "type": "segmentation",
    "license": "Other",
    "ownsCopyright": "1",
    "expectedRuntime": 17.666666666666668,
    "executions": 3
  },
  "input": [
    {
      "mcr2014b": {
        "userdefined": false
      }
    },
    {
      "file": {
        "name": "inputImage",
        "description": "the image to process",
        "options": {
          "required": true,
          "mimeType": "image/jpeg"
        },
        "userdefined": true
      }
    },
    {
      "resultFile": {
        "userdefined": false
      }
    },
    {
      "number": {
        "name": "smooth",
        "description": "smoothing for projection profile matching",
        "options": {
          "required": true,
          "default": 0.0003,
          "min": 0,
          "max": 1,
          "steps": 0.0001
        },
        "userdefined": true
      }
    },
    {
      "number": {
        "name": "slices",
        "description": "number of image slices for projection profile matching",
        "options": {
          "required": false,
          "default": 4,
          "min": 2,
          "max": 8,
          "steps": 1
        },
        "userdefined": true
      }
    },
    {
      "number": {
        "name": "sigma",
        "description": "standard deviation for gaussian smoothing",
        "options": {
          "required": true,
          "default": 3,
          "min": 2,
          "max": 5,
          "steps": 0.1
        },
        "userdefined": true
      }
    },
    {
      "highlighter": {
        "type": "rectangle",
        "userdefined": true
      }
    }
  ]
}

The general section contains overview information about the method, its creator and runtime information.

The input section contains information about parameters this method needs. (For details see Performing a POST request)

Collection information

/collections

Returns a list of all currently available collections in a JSON-Array:

Example Response

{
  "collections": [
    {
      "collection": {
        "name": "wisescratchymonarch",
        "url": "http://127.0.0.1:8080/collections/wisescratchymonarch"
      }
    }
  ]
}

/collection/:collection

Returns detailed information about a collection. Including a list of images that are in this collection.

Example Response

{
  "statusCode": 200,
  "statusMessage": "Collection is available",
  "percentage": 100,
  "images": [
    {
      "image": {
        "md5": "d41d8cd98f00b204e9800998ecf8427e",
        "url": "http://134.21.72.48:8080/files/wisescratchymonarch/original/bnf-lat11641_001r.jpeg",
        "identifier": "wisescratchymonarch/bnf-lat11641_001r.jpeg"
      }
    }
  ]
}

Image Information

/images/:md5/check

Provides information about whether or not an image is available.

Example Response

{
  "imageAvailable": true,
  "collection": "steepwarmarachnid"
}

Retrieving results

/collectionResultUrl

The url for the collection result is built the following:

http://$BASE_URL$/results/$RANDOM_NAME$.json

The response contains the URLs to all existing result files of the computed results on the individual input files.

Example Response

{
	"results": [
		{
			"resultLink": "http://134.21.72.48:8080/results/cornflowerbluepeskyseahog/data_0/data_0.json"
		}
	],
	"collection": "whiteimpartialborer",
	"resultLink": "http://134.21.72.48:8080/results/whiteimpartialborer.json",
	"message": "This url is available for 24 hours",
	"status": "done",
	"statusCode": 202
}

/detailResultUrl

To retrieve the actual results of a computed input image or on input data follow the ``resultLink```URL retrieved from either the collection results or the response from a POST request (see Performing a POST request) The content of follows the following JSON-Schema: responseSchema.json

The URL to retrieve a detailed result has the following scheme: http://$BASE_URL$/results/$RANDOM_NAME$/$data_$x$/data_$i$.json

where:

  • $BASE_URL$: is the base url of the server (e.g. divaservices.unifr.ch)
  • $RANDOM_NAME$: is a random identifier for the execution
  • $i$: refers to the i-th data item that was provided in the request

Example Response

{
  "output": [
    {
      "file": {
        "mime-type": "image/png",
        "name": "krakenBinaryImage.png",
        "options": {
          "type": "bw",
          "visualization": true
        },
        "url": "http://127.0.0.1:8080/results/wrathfulacclaimedsteer/data_0/krakenBinaryImage.png"
      }
    }
  ],
  "status": "done",
  "resultLink": "http://127.0.0.01:8080/results/wrathfulacclaimedsteer/data_0/data_0.json",
  "collectionName": "wrathfulacclaimedsteer"
}

JSON Schemas

DIVAServices builds on JSON-Schemas to validate the integrity of most of its requests. The schemas are vailable in the conf/schemas folder in the repository. For users of DIVAServices the following schemas are of interest:

  • generalAlgorithmSchema.json: contains the definition of the response of the root request to DIVAServices (e.g. the response you receive when going to http://divaservices.unifr.ch)
  • detailsAlgorithmSchema.json: contains the definition when creating a GET request to an existing algorithm
  • responseSchema.json: contains the definition of the default response of a POST request to an algorithm

Uploading data

Image data can be provided using the /upload route described below.

/upload

It is possible to send one, or multiple files at once to store them on the DIVAServices back end. Each POST request to upload leads to the creation of a new collection where all files are stored together.

Images can be provided as the following types:

  • image: the image encoded as base64 string. This should be used as a fallback if the image can not be provided over http.
  • url: A URL to the image
  • iiif: A URL to a IIIF manifest file. The process will automatically fetch all images included in the manifest

name is the name the file should have on the server (without file extension)

Request body for a single image

{
    "files": [
        {
            "type": "url",
            "value": "http://www.e-codices.unifr.ch/loris/ubb/ubb-A-II-0004/ubb-A-II-0004_0002r.jp2/full/pct:25/0/default.jpg",
            "name" : "image"
        }
    ]
}

Request for multiple images

{
	"images":[
		{
			"type":"url",
			"value":"http://www.e-codices.unifr.ch/loris/ubb/ubb-A-II-0004/ubb-A-II-0004_0002r.jp2/full/pct:25/0/default.jpg",
      "name": "image1"
		},
		{
			"type":"url",
			"value":"http://www.e-codices.unifr.ch/loris/saa/saa-4530/saa-4530_029.jp2/full/pct:25/0/default.jpg",
      "name":"image2"
		}
	]
}

Request for IIIF manifest file

{
	"images":[
		{
			"type":"iiif",
			"value":"http://www.e-codices.unifr.ch/metadata/iiif/gf-FlawOf/manifest.json"
		}
	]
}

Example Response

{
	"collection": "orangeinfinitewrasse"
}

Executing Methods

Methods can be executed using POST requests to the URLs of a specific method.

Performing a POST request

A method can be executed with a POST request to the respecting URL (e.g http//divaservices.unifr.ch/api/v2/binarization/krakenbinarization/1)

The method information (see get method information) provides the necessary information about which parameters need to be set.

Parameters with userdefined:false do not need to be explicitly set.

To execute a method create a POST request to the specific method URL.

The example method from the information section can be executed as follows:

Example Request

{
	"parameters":{
		"highlighter":{
			"type":"rectangle",
			"closed":true,
			"segments":[
				[1,1],
				[1,6196],
				[4395,6196],
				[4395,1]
			]
		},
		"smooth": 0.0003,
		"slices": 4,
		"sigma": 3
	},
	"data":[
		{
			"inputImage": "mammothsecondarydromaeosaur/bnf-lat11641_001r.jpeg"
		}
	]
}

Example Response

{
	"results": [
		{
			"resultLink": "http://134.21.72.48:8080/results/sameturbulentynambu/data_0/data_0.json"
		}
	],
	"collection": "sameturbulentynambu",
	"resultLink": "http://134.21.72.48:8080/results/sameturbulentynambu.json",
	"message": "This url is available for 24 hours",
	"status": "done",
	"statusCode": 202
}

The contents are as follows (The schema is defined in: conf/schemas/responseSchema.json:

  • results: An array with the result links to all detailed results of the processed images / inputs
  • collection: The name of the processed collection
  • resultLink: The link to access this result (the url to receive the same response)
  • status: A status message
  • statusCode: A status code

Getting the results

To access the detailed results for an image create a GET response to the resultLink corresponding to the md5 hash of the image. This will return the detailed results:

Example Response

{
  "output": [
    {
      "file": {
        "mime-type": "image/png",
        "name": "krakenBinaryImage",
        "options": {
          "type": "bw",
          "visualization": true
        },
        "url": "http://divaservices.unifr.ch/images/fearfulneedyinchworm/binarizationkrakenbinarization1_0/krakenBinaryImage_0.png"
      }
    }
  ],
  "status": "done",
  "inputImage": "http://divaservices.unifr.ch/images/fearfulneedyinchworm/original/input0.png",
  "resultLink": "http://divaservices.unifr.ch/images/fearfulneedyinchworm/binarizationkrakenbinarization1_0/input0.json",
  "collectionName": "fearfulneedyinchworm",
}

The contents are as follows:

  • output: The outputs produced by the method. Currently the content objects can be quite freely designed but this will change in an upcoming release.
  • status: A status field
  • inputImage: The used input image
  • resultLink: The URL to access this result
  • collectionName: The collection of this image
Add a custom footer
Add a custom sidebar
Clone this wiki locally