Response format specification: f parameter and content negotiation

[jonherrmann]

The current draft allows a client to pass the f-response format parameter and to use the Accept Header mechanism at the same time.

For discussion:

• Since passing different response formats is possible, I would expect an error message in that case. I'm afraid that otherwise, errors are harder to trace.
• Wouldn't the user assume that if he specifies the f-parameter, only the desired format is returned?

One possibility that would allow both mechanisms would be the use of format suffixes, like .json / .hmtl / .xml :

/buildings/{fid}:
    get:
      summary: retrieve a feature
      operationId: getFeature
      tags:
        - Features
      parameters:
        // f parameter dropped
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: A feature.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/buildingGeoJSON'
            application/gml+xml;version=3.2:
              schema:
                $ref: '#/components/schemas/buildingGML'
            text/html:
              schema:
                type: string
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            application/xml:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string

/buildings/{fid}.json:
    get:
      summary: retrieve a feature 
      operationId: getFeatureJson
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: A feature.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/buildingGeoJSON'
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'

/buildings/{fid}.xml
...
/buildings/{fid}.html
...

A generic client could only use the /buildings/{fid} path and use content negotiation mechanism.

[jonherrmann]

Since passing different response formats is possible, I would expect an error message in that case. I'm afraid that otherwise, errors are harder to trace.

OK, just realized that the server would respond with HTTP code 406

[jvanulde]

The f-parameter should be treated like an override. This is useful in instances where you may want to override the default Accept-Header for a particular client. For example, you want to see the JSON representation in a browser which is expecting HTML.

[cportele]

Yes, it is also very useful for clickable links. However, using /buildings/abc.json instead of /buildings/abc?f=json has the same effect and is cleaner (no override necessary and no conflict with the HTTP spec, which does not have a mechanism to override the content negotiation rules).

[jvanulde]

👍

[pvretano]

I have two issues with using extension as an override mechanism.
(1) You cannot convey version or profile information using extensions and for some formats such as GML that can be important. This forces the client to read the stream and then figure out what it got.
(2) You use a different value to request a particular format using an extension then you would using the Accept header (i.e. application/gml+xml; version=3.2 -vs- .gml). The benefit of the f override is that I can use the exact same value as I would in an accept header.
Accept: application/gml+xml; version=3.2 -vs- f=application/gml+xml; version=3.2.

[cportele]

The extension is not an override mechanism. The OpenAPI definition will state the media type that you get back, so there is no guessing what .gml returns.

So far, the idea was (also in the WFS 2.x REST API) to use f with short codes like json, basically the same values as used in an extension. I think, using media types as values for f would be error prone. Just as an example, f=application/gml+xml; version=3.2 would not work as the + would become a space character when decoded. And it makes the URLs less hackable, which I think is a benefit.

[pvretano]

Ah ... ok, that helps for sure. As for F, I am not sure that was the intent in the WFS 2.X REST binding (see Table 38). With regard to encoding the value, I don't think that it is a big deal to expect code to property encode parameter values; they have to do that anyway for other tokens a URL that might include special characters ... no?

[cholmes]

+1 to extensions over the 'f' parameter.

[pvretano]

Ok, I have thought about this issue and this is my conclusion.

I think that the gold standard for format/content negotiation should be the HTTP "Accept" header. I believe everyone is in agreement with this.

However, in cases where we want to embed a link the Accept header will not work and so we are considering using the "f" query parameter or extensions like .json or .gml to request a specific format.

I don't like either of these. The problem with extensions is that they are ambiguous. What does ".gml" mean? Does it mean GML version 2, version 3, GML SF level 0, etc. I know that OpenAPI lets you map an extension to a specific mime type but even that is not satisfactory. First because the use of OpenAPI is optional and whatever else might be used may not have a mechanism to map extesnions in a similar way. Second, even with the extension mapping mechanism, you end up having to map multiple extensions to cover all the versions of GML (for example) that your WFS might offer (i.e. .gml2, .gml3, .gml3sf, etc.)

I don't like the use of the "f" parameter, although I like it better than extensions, because the semantics are different than the HTTP Accept header and that just complicates things.

So, I propose that we define a new parameter named "Accept" that behaves exactly like the HTTP Accept header. Just like the header, a client can use the parameter to specify a list of acceptable media types for the response (see: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). I am not going to get into all of the processing details here but some stuff I remember off the top of my head from the HTTP specification and the Richardson RESTful API book are include: I exepect that the value of the Accept parameter would need to be URL-encoded but that is generally true for query parameters anyway. If no value is specified for the Accept parameter, then the client is declaring that any media type is an acceptable response and the server can generate whatever output format is its default. If an Accept value is specified and no suitable format can be found then the server should throw a 406 exception. Just in case both the Accept header and Accept parameter are specified, the Accept parameter should be ignored.

Finally, since someone implementing a WFS 3.0 will have to include code to handle the Accept header anyway, it makes sense to mostly resuse that code to handle an Accept parameter.

[rcoup]

Just in case both the Accept header and Accept parameter are specified, the Accept parameter should be ignored.

The only practical issue with this is that the extremely common use of the ?Accept= parameter — messing around in a browser to experiment or get queries right — doesn't actually work. Because browsers will normally send an Accept: header. eg. my Chrome sends the following for this issue URL:

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8

This would mean the ?Accept= parameter is never used unless you're not in a browser — in which case you might as well set the Accept: header IMO.

[prushforth]

Having two ways of specifying a value required by the server makes it a DRY problem for the standard. I would pick one and go with it. FWIW you can usually specify headers in browser based fetches, I think.

[pvretano]

As I said in my previous comment I think that the preferred content negotiation mechanism should be the Accept header. I think that the proposed "f" parameter or extensions or my proposed "Accept" parameter is to handle the case where you are using an embedded link (e.g. in a web page). Actually, I don't think that you can set the Accept header for a link in a web page ... but I am not 100% sure. However, Robert's comment is making me think that it should be the other way around ... that is that if the Accept header and the Accept parameter are both specified then the parameter should take precedence. Thoughts?

[lieberjosh]

Perhaps it should be the intersection of header and parameter... The other use for a “format” parameter, though, is where the formats are not semantically equivalent URL itself needs a way of distinguishing between them. —Josh Joshua Lieberman, Ph.D. Principal, Tumbling Walls Consultancy Tel/Direct: +1 617-431-6431 jlieberman@tumblingwalls.com

…

On Jan 18, 2018, at 12:25, Robert Coup ***@***.***> wrote: Just in case both the Accept header and Accept parameter are specified, the Accept parameter should be ignored. The only practical issue with this is that the extremely common use of the ?Accept= parameter — messing around in a browser to experiment or get queries right — doesn't actually work. Because browsers will normally send an Accept: header. eg. my Chrome sends the following for this issue URL: Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8 This would mean the ?Accept= parameter is never used unless you're not in a browser — in which case you might as well set the Accept: header IMO. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.