Server Response to POST Request
This section:
•Overview of possible server responses
•Response: Request failed, no response from server
•Response: Request communicated, but job rejected by server
•Response: Job executed (with positive or negative result)
When a POST request is made successfully to the server, the job is placed in the server queue. A 201 Created message and a result document URI are returned. The job will be processed at the earliest. In the meantime, if the result document is requested, a "status": "Running" message is returned if the job has been started but has not been completed; the client should try again at a later time. A Dispatched state indicates that the job is in the server queue but has not yet been started.
The result of the job (for example, a validation request) may be negative (validation failed) or positive (validation successful). In either case a 201 Created message is returned and a result document is generated. It is also possible that the POST request was not communicated to the server (Request failed), or the request was communicated but the job was rejected by the server (Request communicated, but job rejected). The various possible outcomes are shown in the diagram below.
Request failed, no response from server
When requests cannot be made successfully to the server, the most common errors are those listed below:
Message | Explanation |
404 Not Found | The correct path is: http://localhost:8087/v1/queue/ |
405 Method Not Allowed | Specified method is invalid for this resource. Use the POST method. |
415 Unsupported Media Type | The message header should be Content-Type:application/json. |
Request communicated, but job rejected by server
When requests are made successfully to the server, the server could reject them for the following reasons:
Message | Explanation |
400 Bad Request (bad cmd) | The RaptorXML command is incorrect. |
400 Bad Request (json error) | The request body has a JSON syntax error. |
404 File Not Found | Check file URI (or filepath) syntax of all files named in the command. |
Job executed (with positive or negative result)
When a job (for example, a validation job) is executed, its result can be positive (OK) or negative (Failed). For example, the result of a validation job is positive (OK) when the document to be validated is valid, negative (Failed) if the document is invalid.
In both cases, the job has been executed, but with different results. A 201 Created message is returned in both cases as soon as the job is successfully placed in the queue. Also, in both cases a result document URI is returned to the HTTP client that made the request. After the result document has been created, it can be fetched with an HTTP GET request.
The result document itself might not yet have been created if processing of the job has not yet started or completed. If the result document is requested during this time, a "status": "Running" message is returned if the job has been started but has not been completed; a Dispatched state indicates that the job is in the server queue but has not yet been started.
In addition to the result document, other documents may be generated also, as follows:
•Job executed with result 'Failed': An error log is created in three formats: text, long XML, and short XML. The URIs of these three documents are sent in the result document (which is in JSON format). The URIs can be used in an HTTP GET request to fetch the error documents.
•Job executed with result 'OK': The job is processed successfully and output documents—such as the output produced by an XSLT transformation—are created. If output files have been generated, their URIs are sent in the JSON-format result document. The URIs can then be used in an HTTP GET request to fetch the output documents. Note that not all jobs will have output files; for example, a validation job. Also a job can finish with a state of 'OK', but there might have been warnings and/or other messages that were written to error files. In this case, error file URIs are also sent in the result document (that is, in addition to output documents).
See Getting the Result Document and Getting Error/Output Documents for a description of these documents and how to access them.