Content-Type for service-desc /api - dependant on Accept header?

[allanfrankwork]

Hi

Slightly related to #40.

I'm running the stac-api-validator and the ets-ogcapi-features10 tests on the same service and the check on service-desc are slightly different - this causes the ets-ogcapi-features10 tests to pass and the stac-api-validator to fail (... link must advertise same type as endpoint content-type header, advertised 'application/vnd.oai.openapi+json;version=3.0', actually 'application/json')

The issue is how the service-desc is retrieved;
stac-api-validator does it like so: https://github.com/stac-utils/stac-api-validator/blob/main/stac_api_validator/validations.py#L207 and etc-ogcapi-features10 does it like so: https://github.com/opengeospatial/ets-ogcapi-features10/blob/master/src/main/java/org/opengis/cite/ogcapifeatures10/conformance/core/apidefinition/ApiDefinition.java#L63
(notice the Accept header in etc-ogcapi-features10).

I cannot find any mention of Accept headers in the stac-api spec or in ogc-api-core, so I'm not sure what is "correct" here, so the difference here could just be an implementation detail.

So is it ok if the /api endpoint only returns the correct content-type when asked for it via the Accept header set to this content-type? (Which in our case means that without accept header its just 'application/json')

Thanks.

[heidivanparys]

I cannot find any mention of Accept headers in the stac-api spec or in ogc-api-core, so I'm not sure what is "correct" here, so the difference here could just be an implementation detail.

There is actually a requirement on this in OGC API - Features - Part 1, see https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#req_core_api-definition-success:

A GET request to the URI of an API definition linked from the landing page (link relations service-desc or service-doc) with an Accept header with the value of the link property type SHALL return a document consistent with the requested media type.

So is it ok if the /api endpoint only returns the correct content-type when asked for it via the Accept header set to this content-type? (Which in our case means that without accept header its just 'application/json')

Given the requirement above, I would say yes, and the STAC API validator should be updated. Perhaps @cportele or @pvretano could confirm?

[cportele]

Strictly, there would have been no need to even mention the Accept header in OGC API Features, because HTTP 1.1 is a normative reference and the Accept header is an integral part of the HTTP specification. We mention it, because the "old" OGC Web Service standards and their implementations typically ignored various aspects of the HTTP protocol, including agent-driven content negotiation.

In OGC API Features we use application/vnd.oai.openapi+json, because this was the plan in the OpenAPI group at the time (OAI/OpenAPI-Specification#110). It is very likely now, that it will eventually be application/openapi+json (https://datatracker.ietf.org/doc/draft-ietf-httpapi-rest-api-mediatypes/).

In any case, any HTTP client should use Accept headers for any GET request where the server could offer multiple representations unless there is some other server-specific mechanism to override content negotiation.

[allanfrankwork]

Thanks @heidivanparys @cportele

Yes, I think the issue here is that stac-api-validator issues the GET request without any Accept header and this results in:

• service-desc ({'href': '/api', 'rel': 'service-desc', 'type': 'application/vnd.oai.openapi+json;version=3.0', 'title': 'the API definition '}): link must advertise same type as endpoint content-type header, advertised 'application/vnd.oai.openapi+json;version=3.0', actually 'application/json'

The ets-ogcapi-features10 test for this has the Accept header set to application/vnd.oai.openapi+json;version=3.0, which is then what it will get back as Content-Type.

I guess there is no requirement on the returned Content-Type if the Accept header has not been set. @philvarner have you had time to look at this? We'd love to get this test running as part of our service relese pipeline and this is currently blocking that.

Thanks.

[philvarner]

This should probably be a warning instead of an error. The problem with the API implementation that the validator does not like is the link rel in the root is application/vnd.oai.openapi+json;version=3.0 but the Content-Type header in the response when that link is application/json. This is almost always unintentional. The fix is to either advertise application/json in the link rel or return a Content-Type header of application/vnd.oai.openapi+json;version=3.0 when no Accept is provided.

If the request sets Accept to application/vnd.oai.openapi+json;version=3.0, does the response set the Content-Type to application/vnd.oai.openapi+json;version=3.0?

[allanfrankwork]

Yes, exactly - the server uses application/json as default, but will recognize application/vnd.oai.openapi+json;version=3.0 and return exactly that.

Our API implementation is using springdoc for generating the service documentation. Springdoc uses Content-Type application/json (any other Accept header will result in 406 Not Acceptable) and this clashes with the ets-ogcapi-features10 tests. Content-Type application/json seems normal for public openapi docs like for example https://petstore.swagger.io/

Also I think an earlier version of swagger-ui also required the Content-Type to be application/json. To workaround this the Accept/Content-Type is changed going to/from springdoc, so clients get the representation type they request using the Accept header.

I can change it so that only if clients request application/json, they will get back that content-type - other cases get back application/vnd.oai.openapi+json;version=3.0. This makes stac-api-validator, ets-ogcapi-features10 and swagger ui work at the same time.

I think the reason I did not do this earlier was that swagger ui expected application/json to work but I cannot reproduce this now.

For us another reason is that we have a html version on same url as the swagger json, which we'd also have to put at a different url if this test uses / in the Accept header. We can do this but I still think content negotiation makes sense here.