Support JSON streaming

[maxuai]

Currently the handling of JSON streaming fails due to failing deserialization of the streamed data. As an example we are trying to do that in a python client but I guess in general it applies to all languages.

OpenAPI spec file:

openapi: 3.0.0
components:
  examples: { }
  headers: { }
  parameters: { }
  requestBodies: { }
  responses: { }
  schemas: { }
info:
  title: the test title
  version: '1'
  description: 'The test REST API'
  contact: { }
paths:
  /test/stream:
    get:
      operationId: StreamData
      responses:
        "200":
          description: Ok
          content:
            application/json-lines:
              schema:
                type: string
          headers:
            Content-Type:
              schema:
                type: string
                enum:
                  - application/json-lines
                nullable: false
              required: true
      parameters:
        - in: header
          name: Accept
          required: true
          schema:
            type: string
            enum:
              - application/json-lines

servers:
  - url: http://localhost:5000/api/v1
    description: Local development

gen.yaml file:

configVersion: 2.0.0
generation:
  sdkClassName: SDK
  maintainOpenAPIOrder: true
  usageSnippets:
    optionalPropertyRendering: withExample
  useClassNamesForArrayFields: true
  fixes:
    nameResolutionDec2023: true
    parameterOrderingFeb2024: true
    requestResponseComponentNamesFeb2024: true
  auth:
    oAuth2ClientCredentialsEnabled: false
python:
  version: 0.0.1
  additionalDependencies:
    dev: {}
    main: {}
  authors:
    - Speakeasy
  clientServerStatusCodesAsErrors: true
  description: Python Client SDK Generated by Speakeasy
  enumFormat: enum
  flattenGlobalSecurity: true
  flattenRequests: false
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
  inputModelSuffix: input
  maxMethodParams: 4
  methodArguments: require-security-and-request
  outputModelSuffix: output
  packageName: openapi
  projectUrls: {}
  responseFormat: flat
  templateVersion: v2

I know that there are multiple approaches how to implement the streaming in detail and it probably doesn't make sense to implement the correct handling on your side but as a quick solution it would be perfectly fine to just return the raw response and handle the correct deserilaziation on our side.

[disintegrator]

@maxuai thanks for sharing this issue with us. Streaming of JSON lines is a great idea but we don't support it at this time. However! If you're willing to make a slight tweak to your API to serve text/event-stream (and also enjoy the broad support for server-sent events in many ecosystems) then I'm glad to say we do support that today. Docs.

If you're restricted to streaming in json lines format then please feel free to add a feature request to our public roadmap and we'll discuss this feature within the team.

---

How to model this API with SSE

As an example, instead of serving this:

HTTP/1.1 200 OK
Content-Type: application/json-lines; charset=utf-8
Date: Fri, 02 Aug 2024 09:00:00 GMT
Keep-Alive: timeout=5, max=1000
Connection: Keep-Alive

{"id": "01j49k5whzbwbzchsfxyqsvkfs", "msg": "server started"}
{"id": "01j49k5wj0j89h8j7ejtnq6tqe", "msg": "serving GET /ping"}
{"id": "01j49k5wj01e4w17tc5jq6qfw1", "msg": "server stopped"}
<END OF RESPONSE>

You switch to this:

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Date: Fri, 02 Aug 2024 09:00:00 GMT
Keep-Alive: timeout=5, max=1000
Connection: Keep-Alive

data: {"id": "01j49k5whzbwbzchsfxyqsvkfs", "msg": "server started"}

data: {"id": "01j49k5wj0j89h8j7ejtnq6tqe", "msg": "serving GET /ping"}

data: {"id": "01j49k5wj01e4w17tc5jq6qfw1", "msg": "server stopped"}

<END OF RESPONSE>

Note the double newlines (\n\n) between entries

And in your OpenAPI spec you switch to this:

openapi: 3.0.0
components:
  examples: { }
  headers: { }
  parameters: { }
  requestBodies: { }
  responses: { }
  schemas: { }
info:
  title: the test title
  version: '1'
  description: 'The test REST API'
  contact: { }
paths:
  /test/stream:
    get:
      operationId: StreamData
      responses:
        "200":
          description: Ok
          content:
-           application/json-lines:
-             schema:
-               type: string
+           text/event-stream:
+             schema:
+               type: object
+               required: [data]
+               properties:
+                 data:
+                   type: string
          headers:
            Content-Type:
              schema:
                type: string
                enum:
                  - application/json-lines
                nullable: false
              required: true
      parameters:
        - in: header
          name: Accept
          required: true
          schema:
            type: string
            enum:
              - application/json-lines

servers:
  - url: http://localhost:5000/api/v1
    description: Local development

That should work as expected. You can also change the type of the data field to an object with a schema and we'll handle deserializing each entry for your client code to read.

[maxuai]

@disintegrator thanks, I will give it a try

[maxuai]

@disintegrator FYI: I got it to work but I had to adjust the schema slightly to reflect that data will contain some JSON serialized object as otherwise pydantic would fail as the _parse_event function tries to be smart and will detect if the value is JSON but the model defines it to be string.

 text/event-stream:
   schema:
     type: object
     required: [data]
     properties:
       data:
         properties:
            ...(my object)
         type: object

[disintegrator]

@maxuai, glad to hear this worked out in the end!