Add guidance on support for Prefer header [RFC 7240]

[mkistler]

RFC 7240 describes the Prefer header which can be used on requests to express the client's preference for handling of a request or the content of the response. In particular, Section 4.2 defines the "return=representation" and "return=minimal" preferences, which allow the client to express their preference for either a full representation or "minimal" (generally a 204 No Content) response body.

From the RFC:

the "return=minimal" preference can reduce the amount of data the server is required to return to the client following a request. This can be particularly useful, for instance, when communicating with limited-bandwidth mobile devices or when the client simply does not require any further information about the result of a request beyond knowing if it was successfully processed.

While the Prefer header is similar in spirit to the "view" parameter defined in AEP-157 Partial Responses, Prefer is intended mainly for mutating operations PUT, POST, and PATCH, whereas the "view" parameter is only defined for Get and List methods.

The AEPs should provide guidance on the Prefer header -- whether it should be supported and in what circumstances. This guidance could be added to AEP-157 or in a newly minted AEP.

[toumorokoshi]

This is pretty interesting - probably warrants a live discussion.

it seems like there's a few different way that the header could be used here

1. as a way to change the response shape
2. as a way to modify between long-running operation vs synchronous (although the RFC doesn't provide a lot of definition here)
3. as a way to add a sort of async timeout (wait=)

I feel like we should probably only mention specific use cases. The asynchronous behavior seems a little vague... unless there is an RFC that defines asynchronous APIs?

Also, are ther real-life users cases we can point to? It would be encouraging to have an RFC implemented and be found useful.

[toumorokoshi]

• in the context of AEPs, we dont recommend async.
• we might be able to map the prefer header to views. This is blocked on a common pattern for HTTP mappings to transcodings.

[thegagne]

in the context of AEPs, we dont recommend async.

I'd love to hear more about this and it might be good to have some actual guidance for this on the site.

I think you are referring to async being done poorly via long running HTTP connections - not alternatives such as websockets (not in scope for AEP, but a good thing if you need it), eventing (again, out of scope), or kicking off asynchronous processes via a synchronous call (starting jobs, polling for status).

The last one might be in scope for AEP - but is it discouraged?

[toumorokoshi]

@thegagne I could have been clearer, but what I mean to say is that there is no aep pattern for asynchronous APIs. Adding an asynchronous API does not mean that your API is incompliant - although it's not an AEP client would recognize.

The only guidance we provide w.r.t. to long requests is https://aep.dev/151/.

My general rule of thumb with figuring out what the official AEP stance is to look at the AEPs themselves - if it's not present, we provide no guidance on the topic. Comments are not a binding statement one way or the other.