Consumes/produces should be associated with 'endpoint'

[orubel]

Consumes/produces is at the top outside the bounds of each endpoint. Since conversions are handled on backend (and 90% of conversions are going to be determined by requested content-type), this is redundant and placed in wrong area.

If requested content-type is JSON, over 90% of time the returned content will also be JSON. This conversion is handled on the backend.

Also this content-type is determined at the end-point... NOT at the top of the api doc; each endpoint can handle different conversion.

Also 'produces' exists in endpoint so this is a redundancy

Also.. as 'produces' exists in endpoint, what does one do if backend dynamically handles the conversion; ie. if I request with content-type xml, it converts to resource to XML.

[darrelmiller]

produces and consumes are gone in V3 and are replaced by a content object that is a map of supported media types. Content objects are associated to requests and responses.

[orubel]

How does it deal with dynamically generated response? Say one requests with content-type JSON and I convert resource on backend to JSON or they request with content-type XML and I convert resource to XML??

[MikeRalphson]

In version 2.0 (which is a frozen spec and no-longer changing) the top-level produces and consumes arrays are optional and act as defaults for the common case where the API as a whole produces and consumes the same Content-Types for all or a majority of operations. The aim is to reduce redundancy. As you notice in your other issue, these arrays can be overridden at operation level.

If your API does not honour the standard HTTP Accept header then you should document this fact, but no version of the OAS has a way to specify that the input Content-Type directly affects the output Content-Type.

[orubel]

You are trying to do a 100% coverage when 90% will do and allow end user/client to take care of the conversion for weird cases.

In cases where ACCEPT and CONTENT-TYPE are not the same, end user can do conversion.

In rare cases, you can always FORWARD api data to a service for output to a file, conversion, etc and allow it to change the header but this is not the same thing as the API has finished its job and handed off.

But an API should only return what is requested.

• It covers the 90 percentile of functionality
• it reduces backend processing
• it puts the onus/responsibility on the client/end user for requesting what they want

Mind you this doesn't mean you can't convert JSON/XML or XML/JSON with convertors. You just have to use the content-type to declare what you are sending and it will match. Simple.

One header, one dataType, one conversion. Simple.

[MikeRalphson]

But an API should only return what is requested.

It does. The request comes in the Accept header, not the Content-Type header.

If Tim Berners-Lee had thought he could use one header for both, I'm sure he would have. :smile:

[darrelmiller]

But an API should only return what is requested

I would agree if we were talking about a closed system, on a single platform and single language, but for an HTTP based networked application the amount of value that that is lost by strictly apply this constraint can be huge. Especially in a system that you are trying to evolve. A client request conveys intent, how a server satisfies that intent, and how it responds to it, should be free to change over time.

[orubel]

Tim Berners Lee didn't design the API Pattern. Otherwise he would have realized it had an architectural cross cutting concern in distributed architectures. Ever thought of that? :)

See we can all be snarky. Now lets stick to the discussion.

The ACCEPT header covers those RARE occasions when we want to send back something that doesn't match what we are requesting with.

But they create overhead for our systems as we don't need to handle this.

If I request with 'application/json', 90% of the time I will want back JSON. Reason being is that I am working with JSON.

If I request with 'application/xml', 90% of the time I will want back XML. Reason being is that I am working with XML.

Its deductive reasoning.

The ACCEPT header can be handled by end-user/client in almost ALL cases and in those where it can, API can FORWARD to service.

[orubel]

A client request conveys intent, how a server satisfies that intent, and how it responds to it, should be free to change over time.

@darrelmiller agreed... but that is a different discussion. Reducing backend responsibility and saying that API's should be 'stateless' are two different things (if I am understanding you).

Thats why you would need to abstract communication layer from business logic on backend to avoid the architectural cross cutting concern caused by the api pattern.