The Core Requirements Class defines the requirements for locating, understanding, and accessing coverage resources. The Core Requirements Class is presented in five sections:
-
API Platform: a set of common capabilities
-
Collection Access: operations for accessing collections of
Coverages -
Coverage Access: operations for accessing
Coverageresources -
Parameters: parameters for use in the API-Coverage operations.
-
General: general principles for use with this standard.
The OGC API-Coverages standard is an extension of the OGC API-Common standard. Therefore, an implementation of API-Coverages must first satisfy the appropriate Requirements Classes from API-Common.
API-Common defines a set of common capabilities which are applicable to any OGC Web API. Those capabilities provide the platform upon which resource-specific APIs can be built. This section describes those capabilities and any modifications needed to better support Coverage resources.
The landing page provides links to start exploration of the resources offered by an API. Its most important component is a list of links. OGC API-Common already requires some common links. Those links are sufficient for this standard.
The Landing Page operation is defined in the Core conformance class of API-Common. No modifications are needed to support Coverage resources. The Core conformance class specifies only one way of performing this operation:
-
Issue a
GETrequest on the{root}/path
Support for GET on the {root}/ path is required by API-Common.
A successful response to the Landing Page operation is defined in API-Common. The schema for this resource is provided in Landing Page Response Schema.
link:openapi/schemas/common/landingPage.yaml[role=include]The following JSON fragment is an example of a response to an OGC API-Coverages Landing Page operation.
link:examples/JSON/landingPage_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
Every API is required to provide a definition document that describes the capabilities of that API. This definition document can be used by developers to understand the API, by software clients to connect to the server, or by development tools to support the implementation of servers and clients.
This operation is defined in the Core conformance class of API-Common. No modifications are needed to support Coverage resources. The Core conformance class describes two ways of performing this operation:
-
Issue a
GETrequest on the{root}/apipath -
Follow the
service-descorservice-doclink on the landing page
Only the link is required by API-Common.
A successful response to the API Definition request is a resource which documents the design of the API. API-Common leaves the selection of format for the API Definition response to the API implementor. However, the options are limited to those which have been defined in the API-Common standard. At this time OpenAPI 3.0 is the only option provided.
The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
To support "generic" clients that want to access multiple OGC API standards and extensions - and not "just" a specific API / server, the API has to declare the conformance classes it claims to have implemented.
This operation is defined in the Core conformance class of API-Common. No modifications are needed to support Coverage resources. The Core conformance class describes two ways of performing this operation:
-
Issue a
GETrequest on the{root}/conformancepath -
Follow the
conformancelink on the landing page
Both techniques are required by API-Common.
A successful response to the Conformance operation is a list of URLs. Each URL identifies an OGC Conformance Class for which this API claims conformance. The schema for this resource is defined in API-Common and provided for reference in Conformance Response Schema.
link:openapi/schemas/common/confClasses.yaml[role=include]The following JSON fragment is an example of a response to an OGC API-Coverages conformance operation.
link:examples/JSON/conformance_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
API-Common starts with the assumption that spatial resources are organized into collections. An API will expose one or more collections. The API-Common Collections Conformance Class defines how to organize and provide access to a collection of collections.
API-Coverages observes that a coverage is a collection of measured values. Therefore, a coverage is a collection.
This standard extends the API-Common Collections conformance class to support collections of coverages, then extends that class to support Coverage unique capabilities.
The Collections operation returns a set of metadata which describes the collections available from this API. Each collection on a Coverages API will be a coverage.
http://www.opengis.net/spec/ogcapi_common-1/1.0/req/collections |
This operation is defined in the Collections conformance class of API-Common. No modifications are needed to support Coverage resources. The Collections conformance class describes two ways of performing this operation:
-
Issue a
GETrequest on{root}/collectionspath -
Follow the
datalink on the landing page
Support for both the {root}/collections path and the data link is required by API-Common.
A successful response to the Collections Operation is a document which includes summary metadata for each collection accessible though the API.
link:openapi/schemas/common/collections.yaml[role=include]The following JSON fragment is an example of a response to an OGC API-Coverages Collections operation.
link:examples/JSON/collections_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
Collection Information is the set of metadata which describes a single collection, or in the the case of API-Coverages, a single Coverage. An abbreviated copy of this information is returned for each Coverage in the /collections response.
http://www.opengis.net/spec/ogcapi_common-1/1.0/req/collections |
This operation is defined in the Collections conformance class of API-Common. No modifications are required to support Coverage resources. However, on a coverages API the the collections are also coverages. So in this standard the term coverageid is used instead of collectionid. The two terms are equivalent.
-
Issue a
GETrequest on the{root}/collections/{coverageid}path
The {coverageid} parameter is the unique identifier for a single coverage on the API. The list of valid values for {coverageid} is provided in the /collections response.
Support for both the /collections/{coverageid} path is required by API-Common.
A successful response to the Collection Operation is a set of metadata which describes the collection identified by the {coverageid} parameter.
link:openapi/schemas/common/collectionInfo.yaml[role=include]The following JSON fragment is an example of a response to an OGC API-Coverages Collection Information operation.
link:examples/JSON/collection_info_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
In this clause, API-Common is extended to support Coverage resources.
A Coverage is a collection of measured values. The structure of that collection is defined by the CIS standard. CIS contains four principle components:
-
A
DomainSetcomponent describing the coverage’s domain (the set of “direct positions”, i.e., the locations for which values are stored in the coverage) -
A
RangeTypecomponent which describes the coverage’sRangeSetdata structure (in the case of images usually called the “pixel data type”). -
A
RangeSetcomponent containing the stored values (often referred to as “pixels”, “voxels”) of the coverage. -
A
Metadatacomponent which represents an extensible slot for metadata. The intended use is to hold any kind of application-specific metadata structures.
Each component is directly accessible through the API using standard paths. In addition, collections of elements can be accessed through the following paths:
-
/description: ReturnsDomainSet,RangeType, andMetadata -
/all: ReturnsDomainSet,RangeType,RangeSet, andMetadata
The paths discussed in this section are all branches off of the /collections/{coverageid} root.
The Coverage Offering operation returns a general coverage offering description consisting of envelope, rangetype, and service metadata such as the coverage’s native format
The Coverage Offering operation is defined by the following requirement.
A successful response to the Coverage Offering operation shall meet the following requirement.
link:openapi/schemas/coverage_offering.yaml[role=include]The following JSON fragment is an example of a response to a Coverage Offering request.
link:examples/JSON/coverage_offering_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The Coverage Description operation returns the whole coverage description consisting of domainset, rangetype, and metadata (but not the rangeset)
The Coverage Description operation is defined by the following requirement.
A successful response to the Coverage Description operation shall meet the following requirement.
link:openapi/schemas/coverage_description.yaml[role=include]The following JSON fragment is an example of a response to a Coverage Description request.
link:examples/JSON/coverage_description_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The Coverage Domain Set operation returns the coverage’s domain set definition
The Coverage Domain Set operation is defined by the following requirement.
A successful response to the Coverage Domain Set operation shall meet the following requirement.
link:openapi/schemas/coverage_domainset.yaml[role=include]The following JSON fragment is an example of a response to a Coverage DomainSet request.
link:examples/JSON/coverage_domainset_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The Coverage Range Type operation returns the coverage’s range type information (i.e., a description of the data semantics)
The Coverage Range Type operation is defined by the following requirement.
A successful response to the Coverage Range Type operation shall meet the following requirement.
link:openapi/schemas/coverage_rangetype.yaml[role=include]The following JSON fragment is an example of a response to a Coverage RangeType request.
link:examples/JSON/coverage_rangetype_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The Coverage Range Set operation returns the coverage’s range set, i.e., the actual values in the coverage’s Native Format (see Media Types for ways to retrieve inspecific formats)
The Coverage Range Set operation is defined by the following requirement.
A successful response to the Coverage Range Set operation shall meet the following requirement.
link:openapi/schemas/coverage_rangeset.yaml[role=include]The following JSON fragment is an example of a response to a Coverage RangeSet request.
link:examples/JSON/coverage_rangeset_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The Coverage Metadata operation returns the coverage’s metadata (may be empty)
The Coverage Metadata operation is defined by the following requirement.
A successful response to the Coverage Metadata operation shall meet the following requirement.
link:openapi/schemas/coverage_metadata.yaml[role=include]The following JSON fragment is an example of a response to a Coverage Metadata request.
link:examples/JSON/coverage_metadata_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The Coverage All operation returns all of the above namely the coverage’s domainset, rangetype, meatadata, and rangeset comparable to a GetCoverage response
The Coverage All operation is defined by the following requirement.
A successful response to the Coverage All operation shall meet the following requirement.
link:openapi/schemas/coverage_all.yaml[role=include]The following JSON fragment is an example of a response to a Coverage All request.
link:examples/JSON/coverage_all_example.json[role=include]The requirements for handling unsuccessful requests are provided in HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP status codes.
The API-Coverages standard inherits basic query and subsetting parameters from API-Common. This section provides a short description of each parameter and identifies the relevant requirements.
All of the permissions and recommendations in API-Common regarding the these parameters also apply to API-Coverages implementations.
The Bounding Box (bbox) parameter is defined in API-Common. The following requirement governs use of that parameter in a Coverage API.
The Date-Time (datetime) parameter is defined in API-Common. The following requirement governs use of that parameter in a Coverage API.
The Limit (limit) parameter is defined in API-Common. The following requirement governs use of that parameter in a Coverage API.
Any combination of bbox, datetime and
parameters for filtering on coverage properties is allowed. Note that the requirements on these parameters imply that only coverages matching all the predicates are in the result set; i.e., the logical operator between the predicates is 'AND.'
One consequence of the Limit parameter is that the full result set is not delivered to the user. However, users frequently want to know how big the result set it and how to access the rest of it. The following requirement add information to the response to address that need.
Each HTTP request shall result in a response that meets the following requirement.
The YAML schema for these results is provided in HTTP Response Schema.
link:openapi/schemas/common/exception.yaml[role=include]The Status Codes listed in Table 1 are of particular relevance to implementors of this standard. Status codes 200, 400, 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 Table 1 are not mandatory, but are important for the implementation of a well functioning API. Support for these status codes is strongly encouraged for both client and server implementations.
| Status code | Description |
|---|---|
|
A successful request. |
|
An entity tag was provided in the request and the resource has not been changed since the previous request. |
|
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 |
|
An internal error occurred in the server. |
More specific guidance is provided for each resource, where applicable.
The API Description Document describes the HTTP status codes generated by that API. 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 limit itself 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.