The following section describes the Core requirements class.
A server that implements the OGC API - Processes Standard provides access to processes.
Each implementation of the OGC API - Processes Standard has a single LandingPage (path /) that provides links to:
-
The
APIDefinition(no fixed path), -
The
Conformancestatements (path/conformance), -
The
processesmetadata (path/processes).
Note that additional requirements classes may introduce additional links for inclusion in the landing page.
The APIDefinition describes the capabilities of the server that can be used by clients to connect to the server or by development tools to support the implementation of servers and clients. Accessing the APIDefinition using HTTP GET returns a description of the an API that includes the Processes API defined in this Standard but may include the description of additional components that are part of a broader containing API.
Accessing Conformance using HTTP GET returns a list of URIs of conformance classes implemented by the server.
The list of processes contains a summary of each process offered by the OGC API - Processes implementation, including the link to a more detailed description of the process.
The process description contains information about inputs and outputs and a link to the execution-endpoint for the process.
A HTTP POST request to the execution-endpoint creates a new job. The inputs and outputs need to be passed in a JSON execute-request.
The URL for accessing status information is delivered in the HTTP header location.
After a process is finished (status = successful/failed), the results/exceptions can be retrieved.
The OGC API - Processes Standard utilizes elements of the OGC API-Common Standard. Mapping API - Processes Sections to API-Common Requirements Classes Identifies the API-Common Requirements Classes which are applicable to each section of this Processes API Standard.
API - Processes Section |
API-Common Requirements Class |
The following section defines the requirements to retrieve an API landing page that contains links to Processes API resources but may also contain links to resources that are part of a broader, containing, API.
|
Note
|
The term “…based upon the OpenAPI 3.0 schema…” used in the requirements of this Standard means that OpenAPI 3.0 is used to define:
It also means that unless explicitly excluded these OpenAPI schemas are extensible with additional properties not defined in the schema using the |
link:../../openapi/schemas/common-core/landingPage.yaml[role=include]|
Note
|
This schema can also be obtained from landingPage.yaml.
|
link:../../openapi/schemas/common-core/link.yaml[role=include]|
Note
|
This schema can also be obtained from link.yaml.
|
link:../examples/json/LandingPage.json[role=include]See HTTP status codes for general guidance.
The following section defines the requirements to retrieve an API definition. This API may only implement components of the Processes API defined in this Standard but may define the implementation of a broader API into which the Processes API is embedded.
Every implementation of OGC API - Processes must provide metadata that describe the functional capabilities of the server instance that the API definition provides access to. In this document, this is known as the "API definition". This definition is used by developers to understand the functionality provided by the API endpoing, so software clients can connect to the server, or by development tools to support the implementation of servers and clients.
Note that multiple API definition formats can be supported.
If multiple API definition formats are supported by a server, use content negotiation to select the desired representation.
|
Note
|
Two common approaches are:
|
The API definition document describes the API. In other words, there is no need to include the /api operation in the API definition itself.
The idea is that any implementation of OGC API - Processes can be used by developers that are familiar with the API definition language(s) supported by the server. For example, if an OpenAPI definition is used, it should be possible to create the skeleton of a working client using the OpenAPI definition alone.
See HTTP status codes for general guidance.
To support "generic" clients for accessing servers implementing OGC API - Processes in general - and not "just" a specific API / server, the server must declare the requirements classes it implements and conforms to.
link:../../openapi/schemas/common-core/confClasses.yaml[role=include]|
Note
|
This schema can also be obtained from confClasses.yaml.
|
This example response in JSON is for a server that supports OpenAPI 3.0 for the API definition and HTML and JSON as encodings.
link:../examples/json/ConfClasses.json[role=include]See HTTP status codes for general guidance.
This include the correct use of status codes, headers. etc.
Supporting the method HEAD in addition to GET can be useful for clients and is simple to implement. In particular, the HEAD method is useful in determining the size of a potential response.
Servers implementing Cross-Origin Resource Sharing (CORS) will also implement the OPTIONS method.
Typical HTTP status codes lists the main HTTP status codes that clients should be prepared to receive.
This includes, for example, support for specific security schemes or URI redirection.
In addition, other error situations may occur in the transport layer outside of the server.
| Status code | Description |
|---|---|
|
A successful request. |
|
The request was successful and one or more new resources have been created. |
|
The request was successful but did not generate any content. |
|
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 fulfill it. 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. |
|
The |
|
The target resource is no longer available at the origin server. |
|
The user has sent too many requests in a given amount of time ("rate limiting"). |
|
An internal error occurred in the server. |
|
The server does not support the functionality required to fulfill the request. |
More specific guidance is provided for each resource, where applicable.
When a server encounters an error in the processing of a request, it may wish to include information in addition to the status code in the response. Since Web API interactions are often machine-to-machine, a machine-readable report would be preferred. RFC 9457 addresses this need by providing "Problem Details" response schemas for both JSON and XML.
Access to content from a HTML page is by default prohibited for security reasons if the content is located on another host than the webpage ("same-origin policy"). Cross-origin resource sharing is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served. A typical example is a web-application accessing processes and data from multiple servers.
Two common mechanisms to support cross-origin requests are:
The use of generic media types such as application/json makes it difficult to request or identify different flavors or profiles of a resource. For example, the media type application/json could be used to describe an OGC process description document as well as an OpenEO process description document.
It would thus be useful if there was a mechanism for requesting a profile of a resource. Although there is a new HTTP header, Accept-Profile, that is to be defined in an upcoming Internet-Draft there is currently no standardized was to request a profile of a resource. Existing standards, however, do provide mechanisms for specifying profile information in HTTP headers. Specifically (see Content Negotiation by Profile) profiles of a resource may be requested by:
-
using the
profileparameter if the media type includes provisions for such a parameter (e.g.application/ld+json profile=http://www.w3.org/ns/json-ld#context), -
using the
Accept-Profileheader if the intended media type does not include provisions for aprofileparameter and can, thus, not be specified in theAcceptheader, -
using the
profileparameter with the HTTPPreferheader, -
specified the
Linkheader withrel="profile"in the request headers.
This standard also defines a query parameter, profile, that may be used with an HTTP GET request to specify one or more profiles of a resource that are to be retrieved.
When a content negotiation by profile is performed using one of the above mechanisms, the following response headers should be returned:
-
the
Preference-Appliedheader with theprofileparameter should be returned if content negotiation was performed using thePreferheader, -
the
Content-Typeheader withprofileparameter should be returned if content negotiation was performed using theAcceptheader with a media type includingprofileprovisions.
In all cases of content negotiation by profile, one or more Link (rel="profile") headers indicating the profiles applied should be returned in the response if there is a corresponding URI identifier defined for the profile(s) that can be included as the href of the link.
|
Note
|
This is not always the case (e.g. image/tiff; application=geotiff; profile=cloud-optimized). In such cases, the other the other headers (Preference-Applied and Content-Type) containing a profile parameter may be relevant.
|
|
Note
|
A set of profile URIs for JSON content defined in this Standard can be found in the Profile identifiers table. |
Several resources defined in this Standard (see Retrieve a process list, Retrieve a job list) use the limit parameter to control the maximum number of results that are presented in a response page.
-
The client can request a limit it is interested in.
-
The server likely has a default value for the limit, and a maximum limit.
-
If the server has any more results available than it returns (the number it returns is less than or equal to the requested/default/maximum limit) then the server will include a link to the next set of results.
As an example, using the default/maximum values of 10/1000 from the OpenAPI fragment in requirement /req/core/pl-limit-definition or /req/job-list/limit-definition:
-
If the client asks for 10 results, the client will get 0 to 10 (as requested) and if there are more, a
nextlink; -
If the client does not specify a limit, the client will get 0 to 10 (default) and if there are more, a
nextlink; -
If the client asks for 5000 results, the client might get up to 1000 results (server-limited) and if there are more, a
nextlink; -
If the client follows the next link from the previous response, the client might get up to 1000 additional results and if there are more, a
nextlink.
This Standard provides requirements and recommendations about links in general and the next link in particular at the appropriate resource end points.
This Stadard does not mandate any specific implementation approach for the next links.
An implementation of the Processes API could use opaque links that are managed by the server. It is up to the server to determine how long these links can be dereferenced. Clients should be prepared to receive a 404 response.
Another implementation approach is to use an implementation-specific parameter that specifies the index within the result set from which the server begins presenting results in the response, like offset or the startIndex parameter that was used in WFS 2.0.
An implementation of the Processes API will return no next link, if all selected results have been returned, and the server knows for certain that there are no further results to be presented. However, in some cases, the server may not be aware that it has already returned all selected results. For example, if the request states limit=10 and the query to the backend returns exactly 10 results. The server may not know if there are more results or not (in most cases there will be more results), unless the total number of results is also computed, which may be too costly. The server will then prudently add the next link, and if there are no more results, dereferencing the next link will return an empty results list and no next link. This behavior is consistent with the statements above.
Clients should not assume that paging is safe against changes to the dataset being accesses while a client iterates through next links. If a server provides opaque links these could be safe and maintain the state during the original request. Using a parameter for the start index, however, will not be safe.
This Standard also has recommendations about including a prev link at the appropriate resource end points. Providing prev links supports navigating back and forth between pages, but depending on the implementation approach, it may be too complex to implement.
The following section defines the requirements to retrieve the available processes offered by an implmentation of the Processes API.
It should be noted that the number of processes exposed via the Processes API may be very different than the number of processes offer by a back-end system upon which the Processes API is implemented.
link:../../openapi/schemas/processes-core/processList.yaml[role=include]|
Note
|
This schema can also be obtained from processList.yaml.
|
link:../../openapi/schemas/processes-core/processSummary.yaml[role=include]|
Note
|
This schema can also be obtained from processSummary.yaml.
|
(see also: descriptionType.yaml).
link:../../openapi/schemas/processes-core/jobControlOptions.yaml[role=include]|
Note
|
This schema can also be obtained from jobControlOptions.yaml.
|
The number of process summaries returned depends on the server and the parameter limit.
See the discussion about the limit parameter in the Limit parameter section.
See the discussion about the next links in the Limit parameter section.
See the discussion about the prev link in the Limit parameter section.
GET /processes HTTP/1.1
Host: processing.example.orglink:../examples/json/ProcessList.json[role=include]See HTTP status codes for general guidance.
The following section defines the requirements to retrieve metadata about a process.
See HTTP status codes for general guidance.
This section describes the requirements for executing a process.
Depending on the description of the process and the negotiated process execution mode, process execution may result in the creation of a job resource.
link:../../openapi/schemas/processes-core/execute.yaml[role=include]|
Note
|
This schema can also be obtained from execute.yaml.
|
link:../../openapi/schemas/processes-core/inlineOrRefValue.yaml[role=include]|
Note
|
This schema can also be obtained from inlineOrRefValue.yaml.
|
(see also: valueNoObject.yaml, qualifiedValue.yaml, link.yaml)
link:../../openapi/schemas/processes-core/outputSelection.yaml[role=include]|
Note
|
This schema can also be obtained from output.yaml.
|
link:../../openapi/schemas/processes-core/format.yaml[role=include]|
Note
|
This schema can also be obtained from format.yaml.
|
A process may be executed synchronously or asynchronously.
Which mode a server responds with is a function of the job control options specified in the process description and the presence or absence of the HTTP Prefer header (IETF RFC 7240).
Each process input is a name/value pair that appears in the inputs section of
an execute request as show in the following example:
"inputs": {
"inputName1": <input value 1>,
"inputName2": <input value 2>,
etc.
}The actual name of each input is its identifier as specified by the input’s definition in the process description.
As shown in inlineOrRefValue.yaml, a process input value that is specified in-line in an execute request can be:
-
a simple literal value,
-
an array,
-
a qualified value,
-
a binary value,
-
or a bounding box.
|
Note
|
See also [sc_collection_input]. |
Simple literal values:
A simple literal value can be a string, number, integer or Boolean.
link:../../openapi/schemas/processes-core/valueNoObject.yaml[role=include]|
Note
|
This schema can also be obtained from valueNoObject.yaml.
|
(see also: binaryValue.yaml, bbox.yaml)
A string literal:
"stringInput": "String value"A date string:
"dateInput": "2021-05-24T20:40:13-05:00"A number:
"numberInput": 3.14159An integer:
"integerInput": 10A Boolean:
"booleanInput": trueArray of values:
Array elements, as per inlineOrRefValue.yaml, can be:
-
embedded arrays,
-
or references to values using links.
An array of simple values:
"arrayOfSimpleValues": [1, 2, 4, 10, 7]An array with a single simple value:
"arrayOfSimpleValues": ["a"]An array of arrays of simple values:
"arrayOfArrays": [[1,2,3,4], ["a","b","c","d"]]An array of objects values:
"arrayOfQualifiedValues": [
{
"value": {
"measurement": 10.3,
"uom": "m",
"reference": "https://ucum.org/ucum-essence.xml"
}
},
{
"value": {
"measurement": 10.5,
"uom": "m",
"reference": "https://ucum.org/ucum-essence.xml"
}
},
{
"value": {
"measurement": 10.9,
"uom": "m",
"reference": "https://ucum.org/ucum-essence.xml"
}
},...
],|
Note
|
In an execute request, as per requirement /req/core/process-execute-input-inline-object, object values must be encoded as qualified values. |
Qualified values:
A qualified value is a value that can be optionally qualified with a format parameter.
Qualified values can be used to encode process input values that, according to their definition in the process description, can be of multiple media types. The format parameter is used to identify the specific media type being provided as the process input.
Qualified values can also be used to encode object-valued process inputs in order to avoid ambiguity with the built-in value schemas defined in this standard (i.e. bbox.yaml, link.yaml or qualifiedValue.yaml itself).
The actual value in a qualified value object is specified using the value key. The value of the value key is an instance of value.yaml.
link:../../openapi/schemas/processes-core/qualifiedValue.yaml[role=include]|
Note
|
This schema can also be obtained from qualifiedValue.yaml.
|
(see also: format.yaml)
link:../../openapi/schemas/processes-core/value.yaml[role=include]|
Note
|
This schema can also be obtained from value.yaml.
|
(see also: valueNoObject.yaml)
An example of a complex process input value.
"complexObjectInput": {
"value": {
"property1": "value1",
"property2": "value2",
"property3": "value3"
}
}In this second example, the property, geometryInput has a cardinality of greater than 1 and value instances can be one of a number of enumerated media types. The schema of geometryInput from the OGC process description for the process might be:
"geometryInput": {
"title": "Geometry input",
"description": "This is an example of a geometry input. In this case the geometry can be expressed as a GML or GeoJSON geometry.",
"minOccurs": 2,
"maxOccurs": 5,
"schema": {
"oneOf": [
{
"type": "string",
"contentMediaType": "application/gml+xml; version=3.2",
"contentSchema": "http://schemas.opengis.net/gml/3.2.1/geometryBasic2d.xsd"
},
{
"$ref": "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.json"
}
]
}
},and an instance of this process input in an execute request might be:
"geometryInputs": [
{
"value": "<gml:Polygon gml:id=\"GID1\" srsName=\"urn:ogc:def:crs:OGC::CRS84\"><gml:exterior><gml:LinearRing><gml:posList>-77.024519 38.810529 -77.024635 38.810973 -77.024704 38.810962 -77.024776 38.811239 -77.024957 38.81121 -77.024905 38.811012 -77.024905 38.811012 -77.024865 38.810857 -77.025024 38.810832 -77.025071 38.811012 -77.025203 38.810992 -77.02506 38.810444 -77.024519 38.810529</gml:posList></gml:LinearRing></gml:exterior></gml:Polygon>",
"mediaType": "application/gml+xml; version=3.2"
},
{
"value": {
"type": "Polygon",
"coordinates": [[[ -176.5814819, -44.10896301 ],
[ -176.5818024, -44.10964584 ],
[ -176.5844116, -44.11236572 ],
[ -176.5935974, -44.11021805 ],
[ -176.5973511, -44.10743332 ],
[ -176.5950928, -44.10562134 ],
[ -176.5858459, -44.1043396 ],
[ -176.5811157, -44.10667801 ],
[ -176.5814819, -44.10896301 ]]]
},
"mediaType": "application/geo+json"
}
]In this case, the mediaType parameter is used to indicate the specific type of geometry being passed as input in each case: GML Polygon for the first element of the array and GeoJSON Polygon for the second element.
Binary values:
In some cases, for example to pass through firewalls, binary input values need to be encoded in-line in an execute request as a string.
link:../../openapi/schemas/processes-core/binaryValue.yaml[role=include]|
Note
|
This schema can also be obtained from binaryValue.yaml.
|
Below is an example of an image process input whose media type is defined in the process description. The schema definition for this process input might be:
"schema": {
"type": "string",
"contentEncoding": "binary",
"contentMediaType": "image/tiff; application=geotiff"
}and an example instance value in an execute request might be:
"imageInput": "R0lGODdhNAHCAfcAAAcHDD+Gs4sLDQpDaqGFdaHE54dJPEoECUlGRteKgcdITgokG4hoVkpY\ngNzHwKKkqOLm7RRjlEgpHU9iZ44lHQYqVdmki6doVmhHOMOIeJG20HiDjCcKBglIeadISrso\nJGooFNbN2d2qr8aljyklHwQJQkdvkWaKxIdrb442LidLeGhMTp6LkeP1+Kh3aiUuVAoUHmlu\ngkcwNYdZRmkJDYGcsDFokElVYyk1NsWWhLEPDtmQldrUyoyFhrjo+Nna5d+4tMGstspoXgc4\n...qgu7sSu7qbtCs2u7t6u6rLsrp4u7veu76eO6vyu8w0u8xWu8x4u8yau8shu8y+u8zwu90Su9\n00u91Wu914u92au928u9whsQADs="|
Note
|
Even though the schema indicates that the input type is binary, when the input value is encoded in-line in an execute request, as per requirement /req/core/process-execute-input-inline-binary, the binary value is encoded as base64-encoded string.
|
In this second example, the image input can be one of a number of value types denoted in JSON Schema by the use of the oneOf[] construct. An example schema for this a process input might be:
"schema": {
"oneOf": [
{
"type": "string",
"contentEncoding": "binary",
"contentMediaType": "image/tiff; application=geotiff"
},
{
"type": "string",
"contentEncoding": "binary",
"contentMediaType": "image/jp2"
}
]
}and a JPEG2000 instance example in an execute request might be:
{
"value": "VBORw0KGgoAAAANSUhEUgAABvwAAAa4CAYAAABMB35kAAABhGlDQ1BJQ0MgcHJvZmlsZQAA\nKJF9kT1Iw0AcxV9TpSL1A+xQxCFDdbIgKuKoVShChVArtOpgcumH0KQhSXFxFFwLDn4sVh1c\nnHV1cBUEwQ8QNzcnRRcp8X9JoUWMB8f9eHfvcfcOEOplplkdY4Cm22Y6mRCzuRUx9IogouhH\n ... \nj3Z5mX7/PCPVRJV92rpHK24xcJrzk20+tkeYlCPqcZNO3Lpni1OJWatPCcmgGDEqx7Om6lfa\nppM4k4BTe9+bsn3L9/9/yWhA0PwQGW8ipCZsnZt9lsdrYEM8z/M8z/M8z/M8z/M8z/MzLWY1\nAAAACUlEQVQ871H6P6JI+TxS5Wn2AAAAAElFTkSuQmCC",
"mediaType": "image/jp2"
}Bounding box values:
A process input value instance can be a bounding box.
link:../../openapi/schemas/processes-core/bbox.yaml[role=include]|
Note
|
This schema can also be obtained from bbox.yaml.
|
This schema is meant to be a template for defining bounding box process inputs. If the specified default and enum are suitable for the client’s requirements then this file can be referenced directly in the process description.
|
Note
|
The crs property is defined using an anyOf of either an enumeration or a generic URI string to allow execute requests making use of a CRS other than CRS84 and CRS84h. These may be supported by the server to validate against the canonical OGC schema.
|
Input validation
Process inputs in an execute request and the corresponding process input definition in the process description have a validation relationship. That is to say, the schema of a process input definition from the process description can be used to validate the component of the corresponding process input value in an execute request that is an instance of value.yaml.
Consider a process input named complexObjectInput with the following definition from an OGC process description:
"complexObjectInput": {
"title": "Complex Object Input Example",
"description": "This is an example of a complex object input.",
"schema": {
"type": "object",
"required": [
"property1",
"property5"
],
"properties": {
"property1": {
"type": "string"
},
"property2": {
"type": "string",
"format": "uri"
},
"property3": {
"type": "number"
},
"property4": {
"type": "string",
"format": "date-time"
},
"property5": {
"type": "boolean"
}
}
}
}and the following instance in an execute request:
"inputs": [
.
.
.
"complexObjectInput": {
"value": {
"property1": "value1",
"property2": "value2",
"property3": "value5"
}
},
.
.
.
]The process input value in this execute request is an instance of a qualified value.
For the purposes of validation, the server needs to only validate the component of the qualified value that is an instance of value.yaml against the schema fragment from the OGC process description. Specifically, the validation target is:
{
"property1": "value1",
"property2": "value2",
"property3": "value5"
}|
Note
|
This example makes use of an OGC process description. However, any other process description vocabulary may be used and applied, for the purpose of validation, in a similar manner. |
Overview:
Each process output is a named object that appears in the outputs section of
an execute request. The name of each output is its identifier as specified by the output’s definition in the process description.
Omitted outputs:
Empty outputs:
Output value format:
A process output can be defined in the process description as being of one or more media types. In cases where a specific output can be presented in one of a number of media types, the format parameter in the execute request can be used to indicate the format that should be used to present the process output value in the server’s response.
Output value size:
Since a priori knowledge of the size of any given output is generally not known, hints can be provided to the server to prevent the inadvertent transmission of large volumes of output.
Return preferences signal to a server how output values should be transmitted based on the size of the output and any accompanying return preferences as define defined in IETF RFC 7240.
The way a server responds to a process an execute request is determined by the following parameters:
-
The negotiated execution mode (synchronous or asynchronous),
-
The number of outputs requested,
-
The negotiated content type for the response (via the HTTP Accept header),
-
Any negotiated client preferences (via the HTTP Prefer header).
The following table maps the possible responses based on the combinations of these execute parameters. The column headers denote:
-
Negotiated execute mode: see Execution mode
-
Requested # outputs: The number of requested (whether implicitly or explicitly) outputs in the execute request
-
Return preference: The negotiated return preferences
-
Response HTTP code: The HTTP status code that the server should generate in this context.
-
Response headers: Any required HTTP headers that the server must include in this context.
-
Response media type: The value of the HTTP
Content-Typeheader that the server should generate in this context. -
Response body: A description of the content of the response body in this context.
-
Req./Rec./Perm.: The corresponding requirements/recommendations/permission as per this Standard.
| Negotiated execute mode | Requested # outputs3 | Defined # of outputs | Return preference (Prefer header) |
Response HTTP code | Response headers | Response media type (Content-Type header) |
Response body | Req./Rec./Perm. |
|---|---|---|---|---|---|---|---|---|
sync |
1 |
n/a |
n/a |
200 |
as negotiated |
requested process output |
See requirement: /req/core/process-execute-sync-one |
|
N |
n/a |
none |
200 |
application/json4 |
||||
minimal |
||||||||
representation |
||||||||
async |
n/a |
n/a |
n/a |
201 |
Location to newly created job |
application/json |
|
Note
|
|
|
Note
|
This above table shows all possible combinations of execute parameters that are specified by this Standard. Not all these combinations need to be implemented by a server conforming to this Standard. For example, a server that only offers processes that can be executed synchronously does not need to implement any of the asynchronous requirements. |
|
Note
|
A process output may be requested explicitly or implicitly in an execute request . |
|
Note
|
|
|
Note
|
|
|
Note
|
|
|
Note
|
|
|
Note
|
|
link:../../openapi/schemas/processes-core/results.yaml[role=include]|
Note
|
This schema can also be obtained from results.yaml.
|
The results.yaml schema defines a map using the respective output identifier as the key. The value of an output can be returned as an in-line value or by reference.
When a process is executed synchronously and a single processing output is generated (whether requested implicitly or explicitly in the execute request) the following requirements and recommendations apply:
|
Note
|
The size of a response may be determined without actually transmitting the entire response by using the HTTP HEAD method to retrieve the Content-Length header.
|
Example
In the example below the process "copmpute-spectral-index" has a single output also named "spectral-index-output". This processes is implemented to store the result file in some Web-accessible location. In this example the process is executed synchronously and the single output is requested. According to Execute responses based on number of requested outputs, request HTTP headers and the size of output values., in this case, the server should respond with the output image generated by the process. The server can either stream the response from its Web-accessiblke location to the client OR the server can use a HTTP 303 redirect to point to the result as shown in the example.
Client Server
| |
| POST /processes/compute-spectral-index/execution HTTP/1.1 |
| Content-Type: application/json |
| Link: <https://www.opengis.net/def/profile/OGC/0/ogc-execute-reque|
| st>; rel="profile" |
| |
| { |
| "inputs": { |
| "spectral-index": "ndvi", |
| "input-image": { |
| "href": ".../sentinel-s1-l1c/S1A_EW_GRDM_1SDH_20240201T00375|
| 4_20240201T003859_052358_0654C4_86EE/measurement/ew|
| -hh.tiff", |
| "type": "image/tiff; application=geotiff" |
| } |
| }, |
| "outputs": { |
| "spectral-index-output": { |
| } |
| } |
| } |
|-------------------------------------------------------------------->|
| |
| HTTP/1.1 303 See Other |
| Location: https://www.example.com/resp/job-01/spectral-index.tiff |
| Content-Type: image/tiff; application=geotiff |
| Content-Length: 13101963 |
|<--------------------------------------------------------------------|When a process is executes synchronously and a multiple processing outputs are generated (whether requested implicitly or explicitly in the execute request) the following requirements and recommendations apply:
An omitted "outputs" parameter signals to the process to execute its logic and generate all outputs defined in the process description.
See also: /req/core/process-execute-omitted-outputs.
An "outputs" parameter whose value is empty (i.e. "outputs": {}) signals to a process to execute its logic but to not generate a response body.
See also: /req/core/process-execute-omitted-outputs.
This Standard does not mandate that servers create a job as a result of executing a process synchronously. However, the following permission is given:
For servers that implement this permission and do create a job as a result of synchronous execution of a process, the following requirement applies:
The job reference in the header can then be used to re-fetch the results of the original synchronous execution.
In the case of asynchronous execution, the following requirement applies:
See HTTP status codes for general guidance.
If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process.
The following section describes the requirements to retrieve information about the status of a job.
|
Note
|
In the case where a server supports multiple processing APIs (e.g. OGC API - Processes, OpenEO, etc.) the profile mechanism may be use by non-OGC clients to interact with the /jobs endpoint and request status information in a schema that they recognize. Profile URIs for content defined in this Standard can be found in the Profile identifiers table.
|
link:../../openapi/schemas/processes-core/statusInfo.yaml[role=include]|
Note
|
This schema can also be obtained from statusInfo.yaml.
|
link:../../openapi/schemas/processes-core/statusCode.yaml[role=include]|
Note
|
This schema can also be obtained from statusCode.yaml.
|
The job status information includes several optional date-time fields that represent milestones in the life cycle of a job. The following are recommended for servers that decide to populate some or all these date-time fields:
|
Note
|
Once a job has finished execution and is no longer consuming compute resources, the duration of processing can be computed as finished-started. The updated field, however, may still be revised as the system continues processing outputs, storing results, releasing compute resources, etc.
|
GET /jobs/81574318-1eb1-4d7c-af61-4b3fbcf33c4f HTTP/1.1
Host: processing.example.orglink:../examples/json/StatusInfo.json[role=include]See HTTP status codes for general guidance.
If the process with the specified identifier does not exist on the server, see requirement /req/core/process-exception/no-such-process.
|
Note
|
The size of individual processing results may be determined without actually transmitting the entire result by using the HTTP HEAD method to retrieve the Content-Length header.
|
The way a server responds when retrieving job results depends on:
-
The number of outputs requested (whether implicitly or explicitly) in an execute request.
-
The negotiated content type for the response (via the HTTP Accept header) or lack thereof,
-
Any negotiated client preferences (via the HTTP Prefer header).
The following table maps the possible responses based on the combinations of parameters in the execute request.
The column headers in the following table denote:
-
Requested # outputs: The number of outputs requested (whether implicitly or explicitly) in the execute request.
-
Access path: The API endpoint from which the result(s) can be retrieved.
-
Return preference: The negotiated return preferences.
-
Response HTTP code: The HTTP status code that the server should generate in this context.
-
Response media type: The value of the HTTP
Content-Typeheader that the server should generate in this context. -
Response body: A description of the content of the response body in this context.
-
Req./Rec./Perm.: The corresponding requirements/recommendations/permission as per this Standard.
get results responses based on the input parameter values used on the original execute request.
| Requested # outputs6 | Access path | Return preference (Prefer header) |
Response HTTP code | Response media type (Content-Type header) |
Response body | Req./Rec./Perm. |
|---|---|---|---|---|---|---|
1 |
/jobs/{jobID}/results/{outputID} |
n/a |
200 |
as negotiated |
requested process output value |
See requirement: /req/core/job-results-async-one |
N |
/jobs/{jobID}/results |
none |
200 |
application/json |
||
minimal |
||||||
representation |
|
Note
|
|
|
Note
|
|
|
Note
|
|
|
Note
|
|
|
Note
|
|
The following requirements apply when retrieving the results of a job that was created by executing a process asynchronously OR was created by executing a process synchronously on a server that creates a job even for synchronous execution:
GET /jobs/81574318-1eb1-4d7c-af61-4b3fbcf33c4f/results HTTP/1.1
Host: processing.example.orglink:../examples/json/Result.json[role=include]See HTTP status codes for general guidance.