Dataformats that do not support curvilinear grids

[bramhl]

The /dataformats endpoint describes the supported dataformats in a service. There are many possible dataformats for grids and not all of them may support curvilinear grids but only cartesian grids.

Should the DD-GRID-API only support dataformats that can provide curvilinear grids? If not, maybe the /dataformats response can be extended with an indication whether the dataformat supports reprojecting the grids or can only provide grids in the source projection.

[ "netcdf1p16", "geotiff", "hdf5", "ascii" ]

---

[ { "name": "netcdf1p16", "canReproject" : true }, { "name": "geotiff", "canReproject" : true }, { "name": "hdf5", "canReproject" : true }, { "name": "ascii", "canReproject" : false } ]

[stefhummel]

A comparable suggestion was made by Deltares reviewers. It should be possible to specify which coverage can be provided in which format(s)

[GeriWolters]

It would be good to have different formats. Issue #10 (and best practices of REST) describes that an endpoint should return only one format. So in your example, there would be an additional endpoint for netcdf1p16, for geotiff, for hdf5, etc.

To make that work, maybe the response of dataformats should include the endpoint which makes the format accessible?

[stefhummel]

(During team discussion) Two issues:

1. how to describe which coverage can be provided in which format(s)
2. different end points for different response formats? Ad 1. /dataFormat end point returns all formats present in the system possible dataFormats will be added to the metaData of the coverages (Ad 2.) Only one /data endpoint, to avoid to many different and system specific end points Use .../data?format=<...> when retreiving data If format can not be provided, return invalid request error.

To be discussed: format=<...> mandatory, or default netcdf-CF when ommitted?

[GeriWolters]

/data?format=<...> would mean that one endpoint can return different result types, so would conflict with the one-endpoint, one-result-type principle as discussed in #10.

[stefhummel]

@GeriWolters: True, but if a system provides quite a few different formats we would need to extend the specification with an end point for every format. End points that will lead to 'not implemented' errors in the other systems. Besides of that, the OGC API Coverages that we took as a starting point defines for every end point the "f" query parameter to specify whether the response should be provided in json or in html, so a "format" query parameter apparently is an accepted approach.

[GeriWolters]

In that case: split endpoint into two? One with the regular (and required) REST response and another for the optional responses using the format query parameter?

[caspervdw]

Issue #10 (and best practices of REST) describes that an endpoint should return only one format.

I disagree with this statement. Often one endpoint may return multiple representations of the same data. For example in the Lizard DD-API implementation, we do JSON and HTML:

https://demo.lizard.net/dd/api/v2/sources/e2c43bb3-6d24-4853-be3c-425fa9cab574/?format=html https://demo.lizard.net/dd/api/v2/sources/e2c43bb3-6d24-4853-be3c-425fa9cab574/?format=json

In #10 I argued for a one-data-per-endpoint approach, not for a one-representation-per-endpoint approach. The mechanism through which the representation is determined is called "content negotiation". This mechanism is generally accepted and works the other way around than we are now proposing.

In content negotation, the client specifies what content-type it wants (using request headers or something in the URL). The server responds successfuly or fails with HTTP 406 "Not acceptable" with a list of acceptable content types for that particular resource.

Listing all available content types in a separate endpoint is not common practice. I think a list in the documentation (or OpenAPI scheme?) would suffice. Some reads:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation https://restfulapi.net/content-negotiation/ https://stackoverflow.com/questions/59072058/http-header-to-return-server-available-content-types

To address the main problem of this issue: what if a dataformat is not supported for a particular resource? The normal course of action is then giving a HTTP 406 "Not acceptable" with a list of acceptable content types for that particular resource.

[GeriWolters]

When using content negotiation, I would suggest not doing it by using a query parameter, but by using the appropriate client and server headers.

• The client specifies the requested format using the Accept header.
• The server must respond with the Content-Type header.
• The server can respond with a 406 if the requested format is unsupported.

Just be sure to define somewhere (the wiki, perhaps) an official dictionary specifying the response types: not all will have an official mime type, I suspect. Since the response for 406 isn't defined, I'd also define that, just to make sure there are no differences among the API implementations.

[stefhummel]

(After team discussion/voting) Indeed we will have a format-query-parameter, and to avoid confusion on the expected response we will make it mandatory

[stefhummel]

Should we make dataformat a query parameter on the /coverage end point?

[caspervdw]

The discussion was about the data endpoint. I think we agreed on JSON as a sensible default for the metadata endpoint, so I'd say: no.