ADEQUATE : REST API specification

Content wrapping and stamps

All regular API responses (which are of media type application/json) share the same format:

{ status: XXX, type: "YYY", payload: ZZZ, stamp: "client_defined_string" }

The status contains an integer, the same as the code of the HTTP response itself. The type is either DATA or MESSAGE string. When the type is DATA, the payload contains a serialized domain object. When the type is MESSAGE, than the payload has the following standard format:

{ text: "AAA", additionalResources: [ "BBB", "CCC", ... ], debugContent: "DDD" }

The message itself is stored in the text, which may contain confirmation message or a message associated with an exception, depending on the status code of the response. The additionalResources is an array of URI strings, that may provide the client programmer with additional resources (usually documentation) to help him or her understand the message or debug its causes. The debugContent holds additional piece of information essential in debugging the call (usually stack trace) when the application server is in debug mode. The text and debugContent can be null (or non-existent in the message), although in case of the text this is not recommended. The additionalResources cannot be null, but an empty array at most, when no additional resources can be provided. The wrapping was introduced as a mean of making the interpretation of the response simpler for the client. The client can now determine the basic flow of processing of the response without the need to parse the payload.

The stamp field contains a string, that was sent to server by client in the request that originated the sent response. Clients can add an optional query parameter named stamp (e.g. "&stamp=client-set-string") with a value of their choosing to every request URL, and the server will send it back to them as a part of the response wrapping object.

To save space the following examples present data payloads in an unwrapped form, in which case the type is assumed to be DATA and the status code is as specified for the HTTP response. When the client sends data to server, the wrapping is naturally not used. Also when the returned media type is not an application/json or when the returned content is a result of explicit export (such is the case of the annotated table), the response is also not wrapped and in case of error only the error status is set (as HTTP header) an no wrapped JSON message is sent. Unless specified otherwise, the server can leave fields with null values from the result out.

The following examples use a http://odalic.eu/odalic/ as the API calls URL prefix, where ./odalic is the API root. Strings enclosed with { and } stand for custom identifiers. All calls unless said otherwise require Authentication and authorization via Authorization header with its value set to "Bearer <issued token>".

HTTP error codes and headers

The API follows standard conventions and returns appropriate HTTP status codes. The 500 should be returned only when the server itself fails. Less common codes will be described in individual cases. The server respects and in some cases (export, input download) even discriminates media types set in Accept and Content-Type headers.

Signing up, authentication and authorization

• All API calls apart from those that allow to sign up, confirm registration or change password, require token authentication from the client as introduced in MISSING LINK .
  
  • The authentication is done by passing a token issued by the server for a client in the standard Authorization header. It must start with Bearer <token>, where Bearer is a constant string (a standard way of telling the server which authentication scheme is used) separated from the token by a single space.
• User signs up by providing an email address and password and following the confirmation link sent to the provided address.
• User can set a new password by providing the old one and new one and following the confirmation link sent to the provided address. This also invalidates issued authentication tokens.
• Confirmation and authentication tokens have limited expiration time, set in the server configuration at config/sti.properties.
  
• All registered users share the same role of a common user. Apart from them a singular administrator account is created based on the details provided in the config/sti.properties. This account has all the capabilities of a regular user, but it can also list all the users and impersonate them by adding "users/{userId}" at the beginning of the request path. These URLs are valid for the regular users too, but are unnecessary, because the server has the user already authenticated and accessing other users' resources results in authorization errors.
  
• Note that the signing up, authentication and authorization features require proper server configuration of the mail service, administrator account, appropriate confirmation links and other!
• As a result of this, all tasks and files (but not knowledge bases or their entities) live in separate name spaces and users can only access those which they own. This also means that two users can access the same URL (e.g. when they both named their files the same), but its content will differ. This also helps to maintain partial backward compatibility for the previous version of the API, which assumed a single user.

Users

• (1) POST http://odalic.eu/odalic/users/
• (2) GET http://odalic.eu/odalic/users/ (only for the administrator)
  
• (3) POST http://odalic.eu/odalic/users/confirmations
• (4) POST http://odalic.eu/odalic/users/authentications
• (5) GET http://odalic.eu/odalic/users/{user@odalic.eu}
• (6) PUT http://odalic.eu/odalic/users/{user@odalic.eu}/password
• (7) POST http://odalic.eu/odalic/users/passwords/confirmations
• (8) DELETE http://odalic.eu/odalic/users/{user@odalic.eu} (only for the administrator)
  
• Query (1) signs the user up using the user's chosen credentials (valid e-mail and password; see (US1) for example).
  • This call does not require token authentication.
  • Although the user is signed up, its calls are not authorized until the provided e-mail address is confirmed via the link sent to his or her email. See (3).
• Query (2) allows the administrator to list the active users. It returns array of (US3).
  
  • Administrator's authentication works the same way as for the regular users, see (4).
• Query (3) accepts a confirmation token (see (US2)). When it is valid and identifies a signed-up user, its account is activated.
  • This call does not require token authentication.
  • Only active user are able to authenticate and get the access token issued, see (4).
  • This call is also initiated by a web client, when its user arrives at the address specified in config/sti.properties that was sent within the confirmation e-mail.
• Query (4) accepts user credentials (the same as (1), see (US1)) and validates them against the set of active users. When OK, access token is issued as a response (same format as (US2)).
  • This call does not require token authentication.
• Query (5) only returns the calling user e-mail and role as demonstrated in (US3).
• Query (6) allows the user to change the password. It accepts (US4), which contains the old and new one. The old one is used to authenticate the user.
  • This call does not require token authentication.
  • The change does not take effect until the confirmation token is provided, see (7). 
• Query (7) confirms the setting of the new password. It accepts confirmation token (US2) whose value was sent in the e-mail (the same process as for the user activation).
  • This call does not require token authentication.
  • When the password is changed, all previously issued authentication tokens are invalidated and their use will result in authentication error.

• Query (8) unschedules all the user's tasks, deletes his or her tasks and files and finally deletes the user's entry, thus prevent him or her to log in.
  

(US1)

{ "email": "test@odalic.eu ", "password": "3*(ew4zpor8ad 89z /*09892*(^Y&" }

(US2) 

{ "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzaWdudXAiLCJpc3MiOiJPZGFsaWMiLCJleHAiOjE0ODU3NTQwMzAsImp0aSI6IjkzOTU2MjUyLTk2ZTMtNGE0MC05ZWE3LTlmYzQ1MmM1MTkxMyJ9.d0tIzt8O_P-QhGZHswBF-KbP9v8V1wscLK5Cph1i_a0" }

 (US3)

 { "email": "test@odalic.eu", "role" : "USER" }

(US4)

{ "oldPassword": "3*(ew4zpor8ad 89z /*09892*(^Y&", "newPassword" : "much easier password" }

Files

• (1) PUT http://odalic.eu/odalic/files/{file_name}
• (2) GET http://odalic.eu/odalic/files/{file_name}
• (3) DELETE http://odalic.eu/odalic/files/{file_name}
• (4) GET http://odalic.eu/odalic/files/
• (5)  PUT http://odalic.eu/odalic/files/{file_name}/format
• (6)  GET http://odalic.eu/odalic/files/{file_name}/format
• Query (1) uploads a file description (FS1) of a remote file or a cached local file, depending on the accept type (in which case (FS1)  does not apply, only the file itself is uploaded)
  
  • Identifier 'file_name' must be unique. Please note that the identifier can contain only alphanumeric characters, underscore, dash, space, comma - all must be URL encoded.
  • If the MIME type produced by the client is multipart/form-data, then the server expects only the file itself in the payload under input part label. 
  • If the MIME type produced by the client is application/json, then the server expects only the remote file description containing and assumes that the location is specified by the location attribute in the sent JSON object. The location can contain any valid URL.
  • The upload is non-resumable.
  • There is also available an alternative POST API call at ../files URL for the multiplart/form-data version, which derives the ID from the name of the uploaded file.
  • The format field is optional and allows for a remote file to immediately specify its format. Only the fields in the example (whose names are self-explanatory) are supported. The quoteCharacter, escapeCharacter, commentMarker can be set to null or omitted (in that case a default parser value is set or the parsing is automatic in that aspect). For a file that has been uploaded vie multipart/form-data, a default format (shown in the (FS1) example) is set and must be configured (if not suitable for the data) by a separate subsequent API call (see (5), (6)). The charset field value is expected to be a canonical name recognized by Java NIO (first column at https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html).
    
• Query (2) returns either a file description (FS2) for file with id 'file_name' or the file itself, depending on the MIME type set by the client.
  • If the MIME type is set to application/json, then the file description object is returned.
  • If the MIME type is set to text/csv, then the file specified in the location is provided. In case of remote location, the server attempts to download the file from the location and passes it as its own.
    
  • See (FS2) for output format of the file description. Notice the cached attribute that distinguishes uploaded (cached) files from the remote ones.
• Query (3) deletes the file (if local) and its corresponding file description.
  • Returns HTTP 406 Conflict and an error message containing the IDs of the referring tasks, when the file is still utilized in some task configuration.
    
• Query (4) returns a list of all the files. 
  • See (FS3) below for further details on the returned data.
• Query (5), (6)
  • Only the fields in the payload example (FS4) (whose names are self-explanatory) are supported. The quoteCharacter, escapeCharacter, commentMarker can be set to null or omitted when put (in that case a default parser value is set or the parsing is automatic in that aspect). The charset field value is expected to be a canonical name recognized by Java NIO (first column at https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html).
    

(FS1)

{ "location": "http://odalic.eu/odalic/files/file_name", "format": { "charset" : "UTF-8", "delimiter" : ";", "emptyLinesIgnored" : true, "quoteCharacter" : null, "escapeCharacter" : null, "commentMarker" : null } }

(FS2)

{ "id": "file_name", "uploaded": "yyyy-MM-dd HH:mm", "owner": "no_meaning_in_this_version_just_some_string", "location": "http://odalic.eu/odalic/files/file_name", "format": { "charset" : "UTF-8", "delimiter" : ";", "emptyLinesIgnored" : true, }, "cached": false }

(FS3)

[ { "id": "file_name", "uploaded": "yyyy-MM-dd HH:mm", "owner": "no_meaning_in_this_version_just_some_string", "location": "http://odalic.eu/odalic/files/file_name", "format": { "charset" : "UTF-8", "delimiter" : ";", "emptyLinesIgnored" : true }, "cached": false }, ... ]

(FS4)

{ "charset" : "windows-1250", "delimiter" : ",", "emptyLinesIgnored" : true, "quoteCharacter" : "\"", "escapeCharacter" : "\\", "commentMarker" : "#" }

Tasks

• (1) PUT http://odalic.eu/odalic/tasks/{task_id}
• (2) GET http://odalic.eu/odalic/tasks/{task_id}
• (3) DELETE http://odalic.eu/odalic/tasks/{task_id}
• (4) PUT http://odalic.eu/odalic/tasks/{task_id}/configuration
• (5) GET http://odalic.eu/odalic/tasks/{task_id}/configuration
• (6) PUT http://odalic.eu/odalic/tasks/{task_id}/configuration/feedback
• (7) GET http://odalic.eu/odalic/tasks/{task_id}/configuration/feedback
• (8) GET http://odalic.eu/odalic/tasks/{task_id}/configuration/feedback/input
• (9) PUT http://odalic.eu/odalic/tasks/{task_id}/execution
• (10) DELETE http://odalic.eu/odalic/tasks/{task_id}/execution 
• (11) GET http://odalic.eu/odalic/tasks/{task_id}/result
• (12) GET http://odalic.eu/odalic/tasks/result/rdf-export  
• (13) GET http://odalic.eu/odalic/tasks/{task_id}/state 
• (14) GET http://odalic.eu/odalic/tasks/?states={false, true}&orderedBy={id,created} 
• Query (1) creates a new task definition with the identifier 'task_id'.
  • See (TS1) for the task description format. The id field is optional, but when filled, then it must be equal to the id provided in the URL.
  • Also consumes text/turtle (must be set as the Content-Type of the request) in the format generated by (2) when text/turtle requested.
• Query (2) returns the task definition (TS1).
  • Also produces text/turtle when the Accept header is set to text/turtle.
• Query (3) removes the task. Although the task is deleted, any running computation might not be stopped immediately. 
• Query (4) sets a new task configuration for possible next execution.
  
  • See (TS2) for the format description. The primary base has to always be set to one that is modifiable (see Bases).
  • The rowsLimit field when set to something else than null cuts of the input after the specified number of rows (the rowsLimit must be non-negative when set, and less than or equal to 2³¹ - 1, which is also the maximum supported number of rows for the files). The uploaded files remain intact.
• Query (5) returns the task configuration object (TS2).
  • The usedBases field must be a subset of the available bases. The primaryBase must be one of the used and modifiable ones. The usedBases can be left out or set to null, in which case it defaults to all available bases.
• Query (6) sets a feedback that the algorithm should take into account in case of next execution.
  • See (TS3) for the format description.
    
  • The subjectColumnPositions are a map from knowledge bases to column positions.
• Query (7) returns the feedback set. 
• Query (8) returns the structured input of the task, upon which the feedback can be set.
  • See (TS4) for the format description.
• Query (9) submits the task for execution.
  • Any previous executions must be either finished or cancelled.
  • The execution object format is described in (TS5), the draft flag is ignored for now. Returns 409 Conflict when the task is already running.
    
• Query (10) cancels task execution. Returns 409 Conflict when the task has already finished. 
• Query (11) returns the result of task execution.
  • The result contains the annotations in structured format as described in (TS6).
  • The call waits for the process to finish.
  • There is also an option to PUT the modified result back to server. This usage is discouraged, but some clients may use it to store work in progress when they do not have a capability to keep the results themselves.
    
• Query (12) exports the result (when available) in a chosen (by the MIME type in the Accept header of the request - text/turtle and application/ld+json are supported) format.
• Query (13) return the state of execution.
  • See (TS7) for format description. Notice the reduction and change of name of some states.
• Query (14) returns a list of all tasks.
  • When the state query parameter is present and set to true, than the tasks aggregated with their states are provided: see (TS8) for format description.
  • The state parameter can be left out or set to false, then the results is just an array of individual tasks as described in (TS1).
  • When the orderedBy parameter is present and set to id or if it is missing, the tasks are sorted by their IDs in ascending order. This parameter can be also set to created, then the tasks are sorted by modification time in descending order.
    

(TS1)

{ "id": "task_id", created: "yyyy-MM-dd HH:mm", "configuration": { ... }, "description": "a simple testing task" }

For configuration object description, see below.

(TS2)

{ "input": "file description ID", feedback: { ... }, "usedBases": [ { "name": "DBpedia" }, { "name": "DBpedia German" } ], "primaryBase": { "name": "DBpedia" }, "rowsLimit": 345, "statistical" : false }

(TS3) (All indices are zero-based)

{
    "subjectColumnsPositions": { "DBpedia": [ { position: { index: 5 } }, ... ], "wikidata": [ { position: { index: 2 } }, ... ], ...},
    "columnIgnores": [ // Columns are ignored for the rest of processing.
        { position: { index: 6 } },
        ...
    ],
    "columnCompulsory": [ // Columns are compulsorily processed (class./disamb.) as named entities (even when they are non-named entities).
        { position: { index: 5 } },
        ...
    ],
    "classifications": [
        {
            position: { index: 5 },
            annotation: {
                "candidates": { // Should contain initial and even the proposed candidates, even if they were not chosen.
                    "dbpedia": [
                        {
                            "entity": { "resource": "http://example.com/hoho/Lala", "label": "Ble" },
                            "score": { "value": 0.5 },
                        },
                        ...
                    ],
                    "wikidata": ...,
                    ...
                },
                "chosen": {
                    "dbpedia": [
                        {
                            "entity": { "resource": "http://example.com", label: "Ble" },
                            "score": { "value": 0.5 }
                        },
                        ...
                    ],
                    "wikidata": ...,
                    ...
                }
            }
        },
        ...
    ],
    "columnAmbiguities": [ // Skipping disambiguation in all cells of the specified columns.
        { position: { index: 6 } },
        ...
    ],
    "ambiguities": [ // Skipping disambiguation for the cells provided.
        { position: { rowPosition: { index: 6 }, columnPosition: { index: 6 } } },
        ...
    ],
    "disambiguations": [
        {
            position: { rowPosition: { index: 5 }, columnPosition: { index: 9 } },
            annotation: { ... } // Same as above.
        },
        ...
    ],
    "columnRelations": [
        {
            position: { first: { index: 5 }, second: { index: 9 } },
            annotation: { ... } // Same as above.
        },
        ...
    ],
    "dataCubeComponents": [
        {
            position: { index: 5 },
            annotation: {
                "component": {
                    "dbpedia": "DIMENSION", // Possible values: "DIMENSION" or "MEASURE" or "NONE".
                    "wikidata": ...,
                    ...
                },
                "predicate": {
                    "dbpedia": [
                        {
                            "entity": { "resource": "http://example.com", label: "Ble" },
                            "score": { "value": 1.0 }
                        },
                        ...
                    ],
                    "wikidata": ...,
                    ...
                }
            }
        },
        ...
    ]
}

(TS4)

{ "headers": [ "country", "city", ...], "rows": [ [ "Albania", "Tirana" ], ... ] }

(TS5)

{ draft: false }

(TS6)

Suppose the following input table that will be processed by the algorithm:

The result could look like this:

{
	// Subject columns
	"subjectColumnsPositions" : { "wikidata": [ { position: { index: 2 } }, ... ], "yago": [ { position: { index: 5 } }, ... ] },
	
	"warnings": [ "Failed to disambiguate 7893739ye9y7yad", "Beware of JAG-JAG bird!" ]

	// Column headers annotations
    "headerAnnotations" : [
		// City
        {
			"candidates" : {
				"wikidata" : [
					{
						"entity": { 
							"resource" : "http://www.wikidata.org/wiki/Q515", 
							"label" : "city" ,
                            "prefixed" : "wikidata:Q515",
							"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
							"tail" : "Q515"
						},
						"score" : 0.79
					}
				],
				"yago" : [
					{
						"entity" : { 
							"resource" : "http://yago.org/city", 
							"label" : "city" 
                            "prefixed" : "yago:city",
							"prefix" : { "with" : "yago", "what" : "http://yago.org/" },
							"tail" : "city"
						},
						"score" : 0.5
					}
				]
			},
			"chosen" : {
				"wikidata" : [],
				"yago" : [
					{
						"entity" : { 
							"resource" : "http://yago.org/city", 
							"label" : "city" 
                            "prefixed" : "yago:city" 
							"prefix" : { "with" : "yago", "what" : "http://yago.org/" },
							"tail" : "city"
						},
						"score" : 0.5
					}
				]
			}
		 },
		
		// Country
        {
			"candidates" : {
				"wikidata" : [
					{
						"entity" : { 
							"resource" : "http://www.wikidata.org/wiki/Q6256", 
							"label" : "country",
                            "prefixed" : "wikidata:Q6256" 
							"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
							"tail" : "Q6256"
						},
						"score" : 0.91
					},
					{
						"entity" : { 
							"resource" : "https://www.wikidata.org/wiki/Q7275", 
							"label" : "state",
                            "prefixed" : "wikidata:Q7275",
							"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
							"tail" : "Q7275"
						},
						"score" : 0.65
					}
				],
				"yago" : [
					{
						"entity" : { 
							"resource" : "http://www.yago.org/country", 
							"label" : "country",
                            "prefixed" : "yago:country",
							"prefix" : { "with" : "yago", "what" : "http://www.yago.org/" },
							"tail" : "country"
						},
						"score" : 0.75
					}
				]
			},
			"chosen": { "wikidata" : [], "yago": [] }
		 },
 
		// Population
        {
			"candidates" : {
				"wikidata" : [
					{
						"entity" : { 
							"resource" : "http://www.wikidata.org/wiki/Q33829", 
							"label" : "population" 
                            "prefixed" : "wikidata:Q33829",
							"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
							"tail" : "Q33829"
						},
						"score" : 0.88
					}
				]
			},
			"chosen": { "wikidata" : [], "yago": [] }
		},
 
		// Rating
        {
			"candidates" : {},
			"chosen": { "wikidata" : [], "yago": [] }
		}
    ],
	
	// Cells annotations
	"cellAnnotations" : [
		// 1st row
		[
			// Paris
			{
				"candidates" : {
					"wikidata" : [
						{
							"entity" : { 
								"resource" : "https://www.wikidata.org/wiki/Q90", 
								"label" : "Paris",
								"prefixed" : "wikidata:Q90",
								"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
								"tail" : "Q90"
							},
							"score" : 0.92
						}
					]
				},
			"chosen": { "wikidata" : [] }
			},
 
			// France
			{
				"candidates" : {
					"wikidata" : [
						{
							"entity" : { 
								"resource" : "http://www.wikidata.org/wiki/Q142", 
								"label" : "France",
								"prefixed" : "wikidata:Q142",
								"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
								"tail" : "Q142"
							},
							"score" : 0.92
						}
					]
				},
				"chosen": { "wikidata" : [] }
			},
 
			// 2,240,621
			{
				"candidates" : { "wikidata" : [] },
				"chosen": { "wikidata" : [] }
			},
 
			// 7.9
			{
				"candidates" : {"wikidata" : []},
				"chosen": { "wikidata" : [] }
			}
		],
		
		// 2nd row
		[
			// Prague
			{
				"candidates" : {
					"wikidata" : [
						{
							"entity" : { 
								"resource" : "http://www.wikidata.org/wiki/Q1085", 
								"label" : "Prague",
								"prefixed" : "wikidata:Q1085",
								"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
								"tail" : "Q1085"
							},
							"score" : 0.92
						}
					]
				}
			},
 
			// Empty
			{
				"candidates" : {"wikidata" : []}
			},
 
			// 1,267,449
			{
				"candidates" : {"wikidata" : []}
			},
			
			// 8.1
			{
				"candidates" : {"wikidata" : []}
			}
		],
 
		// 3rd row
		[
			// Melbourne
			{
				"candidates" : {
					"wikidata" : [
						{
							"entity" : { 
								"resource" : "https://www.wikidata.org/wiki/Q3141", 
								"label" : "Melbourne",
								"prefixed" : "wikidata:Q3141",
								"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
								"tail" : "Q3141"
							},
							"score" : 0.92
						}
					]
				}
			},
 
			// Empty
			{
				"candidates" : {}
			},			
 
			// 4,529,500
			{
				"candidates" : {}
			},
 
			// 3.4
			{
				"candidates" : {}
			}
		]
    ],
	
	// Relations between columns (may be sparse)
    "columnRelationAnnotations": {
		// Indicates relations for the 1st column.
		"0" : {
			// Indicates relations between the 1st and 3rd column
			"2" : {
				"candidates" : {
					"wikidata" : [
						{
							"entity" : {
								"resource" : "http://www.wikidata.org/wiki/Property/P1082",
								"label" : "has population",
								"prefixed" : "wikidataprop:P1082",
								"prefix" : { "with" : "wikidataprop", "what" : "http://www.wikidata.org/wiki/Property/" },
								"tail" : "P1082"
							},
							"score" : 0.9
							}
						}
					]
				},
				"chosen" : {
					"wikidata" : [
						{
							"entity" : {
								"resource" : "http://www.wikidata.org/wiki/Property/P1082",
								"label" : "has population",
								"prefixed" : "wikidataprop:P1082",
								"prefix" : { "with" : "wikidataprop", "what" : "http://www.wikidata.org/wiki/Property/" },
								"tail" : "P1082"
							},
							"score" : 0.9
							}
						}
					]
				}
			}
		 }		
    },
	
	// Statistical annotations
    "statisticalAnnotations" : [
		// City
        {
			"component" : {
				"wikidata" : "DIMENSION",
				"yago" : "DIMENSION"
			},
			"predicate" : {
				"wikidata" : [],
				"yago" : []
			}
		 },
		
		// Country
        {
			"component" : {
				"wikidata" : "DIMENSION",
				"yago" : "DIMENSION"
			},
			"predicate" : {
				"wikidata" : [
					{
						"entity" : {
							"resource" : "http://www.wikidata.org/wiki/Q6256",
							"label" : "country",
							"prefixed" : "wikidata:Q6256",
							"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
							"tail" : "Q6256"
						},
						"score" : 1.0
					}
				],
				"yago" : []
			}
		 },
 
		// Population
        {
			"component" : {
				"wikidata" : "MEASURE",
				"yago" : "MEASURE"
			},
			"predicate" : {
				"wikidata" : [
					{
						"entity" : {
							"resource" : "http://www.wikidata.org/wiki/Q33829",
							"label" : "population",
							"prefixed" : "wikidata:Q33829",
							"prefix" : { "with" : "wikidata", "what" : "http://www.wikidata.org/wiki/" },
							"tail" : "Q33829"
						},
						"score" : 1.0
					}
				],
				"yago" : []
			}
		},
 
		// Rating
        {
			"component" : {
				"wikidata" : "NONE",
				"yago" : "NONE"
			},
			"predicate": { "wikidata" : [], "yago": [] }
		}
    ],
    
    // Column processing annotations
    "columnProcessingAnnotations" : [
		// City
        {
			"processingType" : {
				"wikidata" : "COMPULSORY",
				"yago" : "COMPULSORY"
			}
		 },
		
		// Country
        {
			"processingType" : {
				"wikidata" : "NAMED_ENTITY",
				"yago" : "NAMED_ENTITY"
			}
		 },
 
		// Population
        {
			"processingType" : {
				"wikidata" : "NON_NAMED_ENTITY",
				"yago" : "NON_NAMED_ENTITY"
			}
		},
 
		// Rating
        {
			"processingType" : {
				"wikidata" : "IGNORED",
				"yago" : "IGNORED"
			}
		}
    ]
}

(TS7)

READY, RUNNING, SUCCESS, WARNING, ERROR

READY stands for created, not run yet, or cancelled task. RUNNING is self-explanatory, SUCCESS means that result is ready, WARNING indicates that the result is ready with warnings, but requires further user's attention. Finally ERROR means no result was generated; the algorithm halted halfway with fatal error.

(TS8)

[
   {
      "id": "task_name1",
      "description": "a simple testing task",
      "created": "2016-01-01 09:58",

      // Status of all tasks should be present. It is expected UI will be polling only those that are in progress
      "status": "READY", // Follows the state convention.
      "configuration": {
         ... 
      }
   },
 
   {
      /* ... */
   }
]

Bases

(1) GET http://odalic.eu/odalic/bases?modifiable={true|false}

• • Returns array of available configured knowledge bases, see (B1) for payload example (and (B2) for a detail of a single element).
    • The valid values for textSearchingMethod are: fulltext, substring, exact.
      
  • When modifiable is set to true (default, when not set, is false), only knowledge bases supporting proposal (via insertion) are listed.

(2) GET http://odalic.eu/odalic/bases/{name}

• • Returns a specific knowledge base configuration, see (B2) for payload example.
  • When the accepted MIME type is text/turtle instead of application/json, it exports the knowledge base in RDF serialized in to Turtle.
    

(3) PUT http://odalic.eu/odalic/bases/{name}

• • Sets the specific knowledge base configuration, see (B2) for payload example.
  • When the content MIME type is text/turtle instead of application/json, the servers assumes import of the knowledge base in the RDF format (mechanism similar to Tasks import).
    

(4) DELETE http://odalic.eu/odalic/bases/{name}

• • Removes the specific knowledge base configuration.
  • May fail with 409 Conflict when in use by some task.
    

 (B1)

[ {"name" : "German DBpedia", ... }, ... ]

         (B2)

{"name" : "German DBpedia", "endpoint" : "http://de.dbpedia.org/sparql", "description" : "German version of DBpedia", "textSearchingMethod" : "fulltext", "languageTag" : "en", "skippedAttributes" : [ "http://www.w3.org/ns/prov#wasDerivedFrom", ... ], "skippedClasses" : [ "http://www.w3.org/2002/07/owl#Thing", ... ], "groupsAutoSelected" : false, "selectedGroups" : [ "RDF", ... ], "insertEnabled" : true, "insertEndpoint" : "http://de.dbpedia.org/sparql/insert", "insertGraph" : "http://odalic.eu", "userClassesPrefix" : "schema", "userResourcesPrefix" : "resource", "objectProperty" : "owl:ObjectProperty", "datatypeProperty" : "owl:DatatypeProperty", "login" : "bob", "password" : "1234", "advancedType" : "SPARQL", "advancedProperties" : { "eu.odalic.custom.key" : "custom value", ... } }

 Advanced base types

(1) GET http://odalic.eu/odalic/advanced-base-types

• • Returns array of available advanced base types, see (ABT1) for a detail of a single element. 
  • Shared by all users, accessible without users/{userId} part.
    

(2) GET http://odalic.eu/odalic/advanced-base-types/{name}

• • Returns a specific knowledge base configuration, see (ABT1) for payload example. 
  • Shared by all users, accessible without users/{userId} part.

(ABT1)

{"name" : "SPARQL", "keys" : [ "eu.odalic.custom.key", "eu.odalic.another.key", ... ], "keysToDefaultValues" : { "eu.odalic.another.key" : "Default value", ... }, "keysToComments" : { "eu.odalic.custom.key" : "Comment example..." } }

 Predicates and classes groups

(1) GET http://odalic.eu/odalic/groups

• • Returns array of user's defined groups, see (G1) for a detail of a single element. 
     

• • Returns a specific user's defined group, see (G1) for payload example.

(2) GET http://odalic.eu/odalic/groups/{groupId}

(3) PUT http://odalic.eu/odalic/groups/{groupId}

• • Sets user's defined group.
  • See (G1) for payload example.

(4) DELETE http://odalic.eu/odalic/groups/{groupId}

• • Removes the user-defined group. 
  • May fail when the group is used in some base definition with 409 Conflict.
    

(G1)

{"id" : "DBpedia", "labelPredicates" : [ "http://dbpedia.org/property/name", ... ], "descriptionPredicates" : [ "http://dbpedia.org/ontology/abstract" ], "instanceOfPredicates" : [ "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" ], "classTypes" : [ "http://www.w3.org/2000/01/rdf-schema#Class", ... ], "propertyTypes" : [ "http://www.w3.org/1999/02/22-rdf-syntax-ns#Property", ... ]}

Entities

• (1) GET http://odalic.eu/odalic/bases/{base}/entities?query={needle}&limit={20}
  • Returns array of entities (not discriminating classes, resources, properties,...) in the same format as in the Result (without the scores naturally), see (ES1).
    
  • The base is the knowledge base where the search takes place.
    
  • The query is a URL parameter of the string searched for.
  • The limit is the maximum count of provided hits. Can be omitted and then 20 is used as default.
  • Deprecated.
• (2) GET http://odalic.eu/odalic/bases/{base}/entities/classes?query={needle}&limit={20}
  • Returns array of classes in the same format as in the Result (without the score naturally), see (ES1). 
    • The prefixed field contains the same content as the resource field, if the prefix is not defined on the server for the resource URI. Otherwise the prefixed contains the resource URI shortened by the use of prefix defined at config/PrefixMapping.ttl.
    • The prefix is always separated by a colon.
    • When sent to server, the prefixed field is optional and ignored by the server. 
    • The prefix field contains an object consisting of with (the actual prefix string) and what (associated URI) attributes. It is also optional and ignored when sent to server.
    • If the prefix is not defined, it is null or not even present.
      
    • The tail field contains the rest of the string after the prefix separator, when the prefix is defined. Otherwise it is null. It is also optional and ignored when sent to server.
    • The base is the knowledge base where the search takes place.
      
    • The query is a URL parameter of the string searched for.
    • The limit is the maximum count of provided hits. Can be omitted and then 20 is used as default.
• (3) GET http://odalic.eu/odalic/bases/{base}/entities/resources?query={needle}&limit={20}
  
  • Returns array of resources in the same format as in the Result (without the score naturally), see (ES1).
    • The base is the knowledge base where the search takes place.
    • The query is a URL parameter of the string searched for.
    • The limit is the maximum count of provided hits. Can be omitted and then 20 is used as default.
• (4) GET http://odalic.eu/odalic/bases/{base}/entities/properties?query={needle}&limit={20}
  • Returns array of properties in the same format as in the Result (without the score naturally), see (ES1).
    • The base is the knowledge base where the search takes place.
      
    • The query is a URL parameter of the string searched for.
    • The limit is the maximum count of provided hits. Can be omitted and then 20 is used as default.
   

(ES1)

[ {"resource" : "http://www.wikidata.org/wiki/Property/P1082", "label" : "has population", "prefixed" : "wikidataprop:P1082", "prefix" : { "with" : "wikidatapro", "what" : "http://www.wikidata.org/wiki/Property/" }, "tail": "P1082" }, ... ]

Proposing entities

• (1) POST http://odalic.eu/odalic/bases/{base}/entities/classes
  • For payload format see (EP1).
  • The base is the knowledge base where the proposed class will be created. It must support insertion.
    
  • Returns a newly created class, if nothing bad happens. Format conforms to (ES1).
    
• (2) POST http://odalic.eu/odalic/bases/ {base}/entities/resources
  • For payload format see (EP2).
  • The base is the knowledge base where the proposed resource will be created. It must support insertion.
  • Returns a newly created entity, if nothing bad happens.  Format conforms to (ES2).
• (3) POST http://odalic.eu/odalic/bases/{base}/entities/properties
  • For payload format see (EP3).
  • The base is the knowledge base where the proposed property will be created. It must support insertion.
  • Returns a newly created entity, if nothing bad happens.  Format conforms to (ES3) with the exception that domain and range are currently ignored. 
  • The type attribute value is either "data" (indicating "Data-type property") or "object" (for "Object-type" property), with "Object-type" being the default option when the type is missing.
    
   

(EP1)

{"label": "Country", "alternativeLabels": ["State", ...], suffix: "Class:C1033", "superClass" : {"resource" : "https://www.wikidata.org/wiki/Class:C999", "label" : "State formation" } }

(EP2)

{"label": "Prague(city)", "alternativeLabels": ["The capital city of Prague"], suffix: "Resource:R82123", "classes" : [{"resource" : "https://www.wikidata.org/wiki/Class:C1080", "label" : "City" }, ...]}

(EP3)

{"label": "capital", "alternativeLabels": ["seat of government"], suffix: "Property:P23778", "superProperty" : {"resource" : "https://www.wikidata.org/wiki/Property:P99", "label" : "political centre" }, "domain" : {"resource" : "https://www.wikidata.org/wiki/Class:C1080", "label" : "City" }, "range" : {"resource" : "https://www.wikidata.org/wiki/Class:C999", "label" : "State formation" }, "type" : "data"}