A server that implements the Job Management Requirements Class provides the ability to create, update and start jobs.
The HTTP POST method on the /jobs path is used on to create new jobs.
The HTTP PATCH method on the /jobs/{jobId} is used to update the definition of a previously created jobs that are accessible via the Processes API endpoint.
Finally, the HTTP POST method on the /job/{jobId}/results is used to start a job.
Creating or updating a job requires that a formal description of the new or updated jobs be provided by the client. This Standar does not mandate that a specific jobs schema be used. However, this extension defines the following conformance classe:
-
OGC API - Processes - Wrokflow Execute Request, that enables support for OGC API - Processes - Part 3: Wofklows for jobs definitions.
-
OpenEO Process Graph, that enables support for OpenEO-encoded jobs definitions.
Clients implementing the Processes API Part 4 should be prepared to handle any legal HTTP or HTTPS status code.
The Status Codes listed in Typical HTTP status codes are of particular relevance to implementors of this Standard. Status codes 200, 201 and 404 are called out in API requirements. Therefore, support for these status codes is mandatory for all compliant implementations. The remainder of the status codes in Typical HTTP status codes are not mandatory, but are important for the implementation of a well functioning API implementation. Support for these status codes is strongly encouraged for both client and server implementations.
| Status code | Description |
|---|---|
|
A successful request. |
|
The server has successfully completed the operation and a new resource has been created. |
|
The request was accepted for processing, but the processing was not completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. |
|
A successful request with no additional content to send in the response. |
|
The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value. |
|
The request requires user authentication. The response includes a |
|
The server understood the request, but is refusing to execute the request. While status code |
|
The requested resource does not exist on the server. For example, a path parameter had an incorrect value. |
|
The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests. |
|
Content negotiation failed. For example, the |
|
The status code indicates that one or more conditions given in the request header fields evaluated to false when tested by the server. |
|
The server is refusing to process the request because the request content is larger than the server is willing or able to process. |
|
The server is refusing to service the request because the content is in a format not supported by this method on the target resource. |
|
The server understands the content type of the request content and the syntax of the request content is correct, but was unable to process the contained instructions. For example, the submitted resource does not meet a semantic constraint, e.g. a mandatory property is missing. |
|
An internal error occurred in the server. |
|
Note
|
Status code 422 is not yet an official HTTP status code, but is expected to be added by the draft IETF RFC "HTTP Semantics".
|
More specific guidance is provided for each resource, where applicable.
The API Description Document describes the HTTP status codes generated by that API imeplementation instance. This should not be an exhaustive list of all possible status codes. It is not reasonable to expect an API designer to control the use of HTTP status codes which are not generated by their software. Therefore, it is recommended that the API Description Document be limited to describing HTTP status codes relevant to the proper operation of the API application logic. Client implementations should be prepared to receive HTTP status codes in addition to those described in the API Description Document.
See OGC API - Features - Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).
The following diagram illustrates the sequence diagram for deploying a new process to the API:
Client Server
| |
| POST /jobs HTTP/1.1 |
| Content-Type: application/json |
| |
|------------------------------------------------------------>|
| |
| HTTP/1.1 201 Created |
| Location: /jobs/{jobId} |
|<------------------------------------------------------------|See HTTP status codes for general guidance.
If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from [OAProc-2].
The following diagram illustrates the sequence diagram for updating a previously created job. The identifier of the job does not change.
|
Note
|
The new job definition replaces the old job definition. Version control is not discussed in this Standard. |
Client Server
| |
| PATCH /jobs/{jobId} HTTP/1.1 |
| Content-Type: application/json |
| |
|------------------------------------------------------------>|
| |
| HTTP/1.1 200 OK |
|<------------------------------------------------------------|The status code depends on the server. If the server has replaced the job, the response is either 200 (if the response includes additional content) or 204 (if the response has no additional content).
See HTTP status codes for general guidance.
If the request body’s media type is not supported by the server, see requirement /req/deploy-replace-undeploy/deploy/unsupported-media-type from [OAProc-2].
If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from [OAProc-1].
The following diagram illustrates the sequence diagram for starting the execution of a previously created jobs.
Client Server
| |
| POST /jobs/{jobId}/results HTTP/1.1 |
|------------------------------------------------------------>|
| |
| HTTP/1.1 200 OK |
|<------------------------------------------------------------|See HTTP status codes for general guidance.
If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from [OAProc-1].
If the job with the specified identifier is locked, see requirement /req/job-management/update/response-locked from Updating an existing job.
For every job, it is possible to retrieve its original definition. It corresponds to the request’s body used to create or update the jobs.
See HTTP status codes for general guidance.
If the job with the specified identifier does not exist on the server, see requirement /req/core/job-exception-no-such-job from [OAProc-1].