Support for Streams in Responses

[emmanuelproulx]

APIs that download binary data currently must be done by type: string, format: binary. This translates to byte arrays (in Java for example, anyway that's what swagger-ui and swagger-codegen do). But this consumes large amounts of memory if the data is very big, and easily gives out-of-memory errors.

Typically huge blocks of data are sent via streams instead of byte arrays in most remote APIs. This allows for loading only a block of data at a time in memory.

The workaround used to be the 'file' format but this was removed in version 3.

What I propose is a new type: stream (format: binary) which would allow this. As an example, this could map to Spring's ResponseEntity(inputStreamResource,...) on the server side, and a okhttp's ResponseBody.byteStream() on the client side. Lots of HTTP client & server frameworks support streams in API implementations so I'm surprised it doesn't already exist.

[handrews]

@emmanuelproulx type is from JSON Schema and only refers to the data type, not how it is produced or consumed (because JSON Schema is not aware of those things, although Hyper-Schema is).

If you're talking about HTTP chunked encoding then this should be done through documenting the use of the Transfer-Encoding header, which I believe is already possible.

[emmanuelproulx]

Right. I understand. But there are times when you don't want to respond with JSON. As an example there's this standard REST API to retrieve images, IIIF ( http://iiif.io/ ) and it returns images not just JSON. I'd like to come up with a Swagger description of it but I don't know what to put in the 200 response.

responses:
'200':
content:
'image/png':
???

Sure I could put a schema with type: string + format: binary there but in the end it'll keep the entire image in memory which for sure will blow up during performance testing. Anyway that's not how it's done normally in any API framework; they all use streams.

There should be a way (not sure what the best way is) to specify that the returned entity is not JSON and should be treated as a stream. In OpenAPI 2 there was the "file" type that was used for that purpose but it's gone now.

Would you have a good idea by any chance?

[handrews]

If your content is image/png then it's not JSON. Looking at the Media Type Object the schema field is not required. So I'm not sure you even need one (although I'd defer to the TSC members on this- my expertise is mostly JSON Schema/Hyper-Schema).

If you do need one, it would have to be {"type": "string", "format": "binary"} AFAICT. If that causes something to be held in memory then that sounds like a problem with whatever tooling you are using, and you'll need to open an issue with them.

[emmanuelproulx]

Yes, as I said, right now I'm using swagger-codegen and {"type": "string", "format": "binary"} maps to a byte array. The problem is, there's no way in swagger-codegen to specify a byte array or stream because it relies on the the OpenAPI standard definition which doesn't differentiate between the two. Which is exactly why I'm suggesting we do differentiate by introducing a new type.

The alternative is to add a non-standard feature only in swagger-codegen, which is not ideal.

[handrews]

@emmanuelproulx these are orthogonal concerns- the Media Type Object is just describing the response contents. Whether or not chunked encoding is used is set in headers in the Response Object.

[darrelmiller]

@emmanuelproulx My recommendation in the past has been to use a stream by default and a byte array only if there is a maxlength defined.

[handrews]

@darrelmiller why wouldn't this be indicated through headers? I'm apparently misunderstanding something here.

[darrelmiller]

@handrews You definitely can advertise that a server supports chunk encoding for a particular response using a header declaration. And I agree chunk-encoding and client side data representation are orthogonal concerns.

If the OpenAPI description wants to hint to the client that the result can be stored in a fixed size byte array, then they should indicate that the response has a limited size using maxLength.

Arguably, you can wait until you get the content-length response header until you allocate the byte array, but arguably HTTP responses are self descriptive so OpenAPI descriptions are optional in the first place :-).

My perspective is that the current behaviour of the Swagger tools is less than optimal and they should default to a Stream datatype if the OpenAPI description doesn't limit the response size.

[handrews]

@darrelmiller makes sense, thanks!

[darrelmiller]

We discussed this in the #1585 TSC meeting and the consensus was that tooling should interpret {"type": "string", "format": "binary"} as a stream of bytes and the maxLength schema property could be used to indicate that it can be loaded into a fixed length byte array. That doesn't preclude tooling from loading fixed length data into a stream, nor using the content-length header to load a chunked payload into a fixed length array.

[AtosNicoS]

Are there any updates on this? The spec representation seems to be clarified, are we just waiting for updated tooling?