Task
Asynchronous jobs are handled via an intermediate Task resource. A resource, submitting an asynchronous job should return the URI of the task.
REST operations
Description | Method | URI | Parameters | Result | Status codes |
Get a list of all available tasks | GET | /task | [?query=task status as in opentox.owl] |
List of URIs text/uri-list RDF representation application/rdf+xml |
200,503,401 |
Get the representation of a running task | GET | /task/{id} | Task representation in application/rdf+xml |
200,201,202,404,503,401 | |
Delete (cancel) a task | DELETE | /task/{id} | 200, 404, 503,401 |
Creating a task (POST call to another OpenTox web service)
An asynchronous task is returned from services that initiate a propably long running job (e.g. large dataset upload, model creation, model prediction). The return value of these POST calls is specified in the API as 'returns TASK or <result> URI' (<result> could be for example a model, created by an algorithm). The client can distinguish the result value type via http status code.
The result of a POST call to an OpenTox web service:
HTTP status code (returned by service) |
Accept header (specified by the client) |
HTTP result body (returned by service) |
202 | text/uri-list | Task URI |
application/rdf+xml | Task object in RDF/XML format |
|
200 | text/uri-list |
<result> URI |
application/rdf+xml | Task object in RDF/XML format |
Background info on status code 202:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html 10.2.3 202 Accepted The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The entity returned with this response SHOULD include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.
Accessing a task (GET)
After a task was created, the state of the job that is running in the background can be requested via GET call. The result URI of the job can be found in the resultURI field of the task as soon as the task has finished. The status code indicates whether the task is still running (202), another task resumes the job (201) or the task is completed (200).
The result of a GET /task/{id}:
Task state |
HTTP status code (returned by Task service) |
Accept header (specified by the client) |
HTTP result body (returned by Task service) |
Task is not completed |
202 |
text/uri-list | Task URI |
application/rdf+xml | Task object in RDF/XML format | ||
Another task resumes the job |
201 | text/uri-list | URI of the other task that resumes the job (value of resultURI) |
application/rdf+xml | Task object in RDF/XML format | ||
Task is completed |
200 | text/uri-list | <result> URI (value of resultURI) |
application/rdf+xml | Task object in RDF/XML format |
RDF representation
The asynchronous task is represented by OpenTox Task object, as defined in OpenTox ontology http://www.opentox.org/api/1.1/opentox.owl#Task
A task object has the following properties:
- dc:date - specifies when the task has been created; of type xsd:dateTime ;
- dc:creator - specifying the URI of the resource, where the task has been created, of type xsd:anyURI ;
- dc:title - human readable title of the task, of type xsd:string;
- dc:description (optional , eventually might be used for error reporting ?)
- ot:hasStatus - one of "Cancelled", "Completed", "Running", "Error", "Queued"
- ot:percentageCompleted - of type xsd:float
- ot:resultURI - specifies the URI(s) of the newly created resource, of type xsd:anyURI ; present only if status is "Completed"
Incompleted task (N3 notation)
@prefix ot: <http://www.opentox.org/api/1.1#> . @prefix dc: <http://purl.org/dc/elements/1.1/> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix owl: <http://www.w3.org/2002/07/owl#> . @prefix xsd: <http://www.w3.org/2001/XMLSchema#> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . [] a ot:Task ; dc:date "1269258300474"^^xsd:dateTime ; dc:creator "http://host/model/149389"^^xsd:anyURI ; dc:title "Apply Classification: Decision tree J48 to http://host/dataset/1"^^xsd:string ; ot:hasStatus "Running"^^xsd:string ; ot:percentageCompleted "50.0"^^xsd:float .
Completed task (N3 notation)
@prefix ot: <http://www.opentox.org/api/1.1#> . @prefix dc: <http://purl.org/dc/elements/1.1/> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix owl: <http://www.w3.org/2002/07/owl#> . @prefix xsd: <http://www.w3.org/2001/XMLSchema#> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . [] a ot:Task ; dc:date "1269258300474"^^xsd:dateTime ; dc:creator "http://host/model/149389"^^xsd:anyURI ; dc:title "Apply Classification: Decision tree J48 to http://host/dataset/1"^^xsd:string ; ot:hasStatus "Completed"^^xsd:string ; ot:resultURI "http://host/dataset/666"^^xsd:anyURI ; ot:percentageCompleted "100.0"^^xsd:float .
HTTP status codes
Interpretation | Nr | Name |
Success | 200 | OK The task is completed, the representation contains URI of the result |
Pointer to other Task |
201 |
Task has finished, another Task resumes the Job (URI is specified in result) |
Processing | 202 | Accepted, processing has not completed |
task_id is wrong | 400 | Bad Request |
Not Authorized | 401 | Not Authorized |
Task for specific id not found | 404 | Not Found |
Error | 500 | Internal server error |
Service not available | 503 | Service unavailable |
When a task fails, there must be a way to communicate to the client the reason of this failure and which side of the communication (server or client) is to blame. OpenTox, being a distributed computing system, has to provide a clear insight on what happens in the background and the same holds for cases of exceptional events. An exceptional event might occur during the execution of an asynchronous task (when the task will have the status 'Error') or outside the context of a task (e.g. a user asks for a non-existing resource). In what follows we provide details regarding the RDF representation of Error Reports and explain how error reports are related to tasks. Proper formal error reporting is essential for helping services
understand the reason something went wrong and take proper actions. The
main issues encountered so far are summarized as follows: Taking these into account we conclude that there is a need for an error reporting API meeting the following requirements: The first question to be addressed is what information should an
error report contain and how could these be provided in a structured way
to meet the requirements stated above. So, an error report should
contain at least the following information: An RDF representation of the error report can be easily obtained by a proper extension of the API. Here are some examples of how an error report may look like: An hierarchical structure can be also adopted for the error codes. For example: . These should be followed by a corresponding HTTP status code and a brief explanation. For example: Progression Of Task States [ot:hasStatus]
Error Reporting: a human+machine-friendly aspect
Motivation
request and it should not be repeated but provides no information about the error itself.
a 400, 404, 500, or any other kind of error.
to the developers but is not much help towards automating subsequent actions (its not easily machine-readable). Requirements
status code in that case should be 502, but the error report will provide the details needed.First steps
gamma
should be positive, a hint can be something like "The value you
provided for the parameter gamma is negative while it accepts only
positive values".Error Reports in RDF
x a ot:ErrorReport;
ot:errorCode err:PredictionFeatureNotInDataset;
ot:actor <http://opentox.ntua.gr:3000/algorithm/svm>;
ot:message "The prediction feature you provided is not contained in the dataset"^^xsd:string;
ot:errorDetails "The prediction feature you provided (http://someserver.com/feature/100) is not contained
in the dataset. Available features are:
** List of features goes here **"^^xsd:string .
x a ot:ErrorReport;
ot:errorCode err:CannotGeneratePredictrionFeature;
ot:actor <http://opentox.ntua.gr:3000/algorithm/svm>;
ot:message "An error was received from the feature service and the prediction feature could not be created";
ot:errorDetails "The remote server at http://some.opentox_server.net/feature"^^xsd:string;
ot:errorCause y .
y a ot:ErrorReport;
ot:errorCode err:ServiceUnavailable;
ot:actor <http://some.opentox_server.net/feature>;
ot:message "The service is temporarily unavailable. Please try again after 10 minutes"^^xsd:string .
to post the feature to service C. If the request succeeds, then the error received from service B is omitted. But if both requests fail then the error report returned to the client should include the error reports produced by
both remote services B and C. Here is an example of such a representation:
x a ot:ErrorReport;
ot:errorCode err:CannotGeneratePredictrionFeature;
ot:actor <http://opentox.ntua.gr:3000/algorithm/svm>;
ot:message "An error was received from the feature service and the prediction feature could not be created";
ot:errorDetails "The remote server at http://some.opentox_server_A.net/feature"^^xsd:string;
ot:errorCause [y z] .
y a ot:ErrorReport;
ot:errorCode err:ServiceUnavailable;
ot:actor <http://some.opentox_server_A.net/feature>;
ot:message "The service is temporarily unavailable. Please try again after 10 minutes"^^xsd:string .
z a ot:ErrorReport;
ot:errorCode err:NotAFeatureRepresentation;
ot:actor <http://some.opentox_server_B.net/feature>;
ot:message "The RDF representation you posted is not recognized as the representation of a feature"^^xsd:string
ot:details "The posted RDF is syntactically correct but no feature resource was found in it."^^xsd:string.
err:NotAFeatureRepresentation rdf:subclassOf err:ImproperRDFRepresentation
err:ImproperRDFRepresentation rdf:subclassOf err:BadRDFContent
err:BadRDFContent rdf:subclassOf err:SomeOtherException
Current Challenges
As a first step towards the implementation of Error Reporting API is to
make a list of all possible errors a service might encounter and
establish an enumeration of error codes
Error Code
Description
HTTP Status Code
PredictionFeatureNotInDataset
The prediction feature provided by the client is not included in the training dataset
400
References/Links