An SSE Proposal

[robertlagrant]

Introduction

Server-Sent Events are an HTTP-based way for servers to push data to clients as "events", blessed with an official specification in Javascript on the client side. Unlikely websockets or gRPC it can't do bidirectional communication, but it also sticks to text-based HTTP rather than "upgrading" to a binary protocol.

The latter point I believe makes it suitable for description as a REST resource. For example it allows the description of complex resources such as "progress" - the server performs a long-running activity; this activity's progress can be modelled as a REST resource using SSE.

Given SSE is a free-text medium, just as HTTP is, I believe it would be wise to add certain opinions to the OpenAPI way of specifying it. This proposal is of what I think those opinions could be and why, and a possible resulting OpenAPI description.

The proposed opinions

• While SSE can send any text data, it should be limited here to JSON. This allows the usual OpenAPI descriptors to be used in describing the shape of event data. In the future XML could be added if it were popular.
• SSE has optional event names to accompany a particular data push. This allows clients to parse different event types differently, based on the event name. Event names should be mandatory in the OpenAPI specification, to allow simple generation and use of different possible events on the client side.
• SSE has an event ID to send. My feeling is this should be made available in clients if it is present, but as it is more for clients to request from a certain point in a message stream, it does not need to be specified in OpenAPI.

The proposed format

The format tries to incorporate standard OpenAPI semantics.

The only deviation is how the event type is specified, as a key under the anyOf node. I considered an x- property, such as x-event-name in the component schema, but that would be difficult with any resources that are used in multiple event types. It also makes the event name appear optional, which I think would be a mistake. Open to alternatives, of course.

responses:
  "200":
    description: "Activity in progress"
    content:
      text/event-stream:
        anyOf:
          "event_in_progress":
            schema:
              $ref: "#/components/schemas/EventProgess"
          "event_completed":
            schema:
              $ref: "#/components/schemas/EventWithCompletionData"

Additional comments:

• The use of anyOf may not be what that is intended for, but it appears to be the best fit to my current understanding.
• I wonder if each event could have its own content-type within the SSE format. That would allow any type of data in each event - clunky example:

  anyOf:
    "event_in_progress":
      eventContentType: "application/json"
      schema:
        $ref: "#/components/schemas/EventProgess"
    "event_completed":
      eventContentType: "text/plain"
      schema:
        $ref: "#/components/schemas/EventWithCompletionData"

Thanks for reading

I'd love feedback on this proposal. Very happy to work asynchonously in the Github-style, but also happy to join the calls and talk through it at some point, if there's time available in them.

P.s.

There was an issue opened on this already. I believe I've read the entire thing, but thought a new discussion might be a better (re)-starting place. Many thanks to nikojpapa's comment that the proposed format was originally based on.

[lornajane]

I'm not familiar with server-sent events, can you say something about why something like AsyncAPI for websockets doesn't serve this use case?

Is a server-sent event "response" (from server to client) sent in response to a request? If not, does the existing webhook feature work for this use case?

[robertlagrant]

Why not websockets/webhooks?

I'm not familiar with server-sent events, can you say something about why something like AsyncAPI for websockets doesn't serve this use case?

Is a server-sent event "response" (from server to client) sent in response to a request? If not, does the existing webhook feature work for this use case?

Sure! SSE is a different protocol and format to websockets, so using a websocket interface description wouldn't allow servers and clients to build SSE-specific tooling. Same with webhooks. As far as I understand it, webhooks are a regular HTTP request; just initiated by the server. SSE works slightly differently to both of these.

What is SSE?

SSE is a normal client-initiated request with multiple events being pushed down the same response. You could think of it like old-school HTTP long polling, but with a formalised API in Javascript and HTTP, so tooling can be built on top of it.

Browsers have support for it already, with the EventSource API. The API allows connection, autoreconnection if network conditions change, resumption of processing from the point the client last saw, and interpretation of SSE-formatted messages into Javascript-land.

SSE's format

The client initiates an HTTP GET request, e.g. to /progress_monitor?task_id=12345}.

The endpoint responds with a content-type: text/event-stream response. This lets the client know to expect SSE.

The SSE format at its most basic looks like this:

data: my_data

Or multi-line:

data: my_data
data: some more data
data: even more data

In each case a message is one or more data: lines, with a blank space after.

Messages can have an ID (see my first post; I would recommend that a specification such as OpenAPI mandates this, to simplify tooling creation - then a client can interpret multiple types of message based on event type):

event: progress
data: { "progress_percentage": 98}

event: progress_complete_success
data: {"new_resource_id": "12345"}

# or
event: progress_complete_failure
data: {"failure_reason": "Splines did not reticulate fast enough"}

Rationale

Why SSE at all?

• only pushes server->client, so is much simpler for this use case than a general-purpose message procotol
• has a nice and simple API on the web browser / Javascript side to consume and resume messages if a connection drops or transfers
• removes the need for long polling/comet/regular polling without totalling changing from a REST API to websockets or similar
• registers against a URL, so it can be used to describe RESTful resources - can be more structured than the more free-form general messaging cases such as websockets/gRPC
• still HTTP, so all headers work, such as accept-language and authorization
• client-initiated, so all the usual firewall rules that an application needs already will also let it through
• lighter than HTTP polling, as headers aren't needing to be resent or re-received

Why should OpenAPI support this (and why OpenAPI and not AsyncAPI):

• just regular text-based HTTP, not a separate protocol like websockets (which needs HTTPS and is a binary protocol)
• more RESTy than messaging-y
• fills a gap - describes resource types regular HTTP/REST currently cannot without polling, e.g. creating a resource that changes over time such as a progress monitor

[LasneF]

adding this level would be a kind of breaking change .

i am even wondering in fact OAS does not already supports SSE

the content type specify that it is server side event , in a way , then the schema could then just be the anyOf , one of the schema (or oneOf may be ) that would defined the schema of the data part of a SSE

that said it would requires promotion about SSE support , what is covered,
having a particular section for this specific media type , a kind of what exists for XML

responses:
  "200":
    description: "Activity in progress"
    content:
      text/event-stream:
            schema:
              anyOf: 
                - $ref: "#/components/schemas/EventProgess"
                - $ref: "#/components/schemas/EventWithCompletionData"
                

that said it is does not make it so clear ,

[handrews]

@LasneF I agree with you- this is a similar challenge to supporting streaming JSON formats (e.g. application/json-seq), which just need to be treated as a JSON array where each array element is a document in the stream.

In other words, both of these are solved by defining a mapping between the media type and the JSON Schema data model. We already do this (in a much more complex way involving the Encoding Object) for application/x-www-form-urlencoded and multipart/form-data message bodies.

Because the streaming JSON mapping is so simple, I've proposed including it in OAS 3.2 (and adding more comprehensive yet simplified mapping support in 3.3). It looks like text/event-stream is similarly straightforward, where it could just be modeled as a JSON object. Honestly, I can't tell why they didn't do that, except perhaps that JSON doesn't support comments. But for OAS, we don't care about comments either way, so treating it as if it were a JSON object that doesn't have any nesting should work.

So that could go in 3.2 easily enough, and might be sufficient to solve this problem?

[robertlagrant]

Thanks both for the commentary. @LasneF would you mind expanding on how this would be a breaking change?

[handrews]

This would be slightly more complex than I said earlier as text/event-stream allows multiple lines with the same field name. But that's also true of other things we need to model such as HTTP headers and their parameters. And technically, application/x-www-form-urlencoded is ordered and allows the same key to be used multiple times. So we might need to handle this in 3.3 when we tackle those modeling problems rather than being able to do a quick simple thing in 3.2.

[robertlagrant]

To quickly follow up on the call - thanks all for discussing this relatively niche feature!

I thought it would be good to gather the above options for how to describe SSE.

Assume JSON messages; infer event type

E.g.

responses:
  "200":
    description: "Activity in progress"
    content:
      text/event-stream:
        schema:
          anyOf: 
            - $ref: "#/components/schemas/EventProgess"
            - $ref: "#/components/schemas/EventWithCompletionData"

This is lovely and simple. The issue it has is it does not have a way to associate an event type with a particular message format. This could be perhaps convention-based, so #/components/schemas/EventProgess has event type EventProgess, although that has the small downside of making clients potentially a little brittle to changes in the API internals.

Assume JSON messages; specify event type

E.g. (may not be idiomatic OpenAPI, but hopefully it gets the point across)

responses:
  "200":
    description: "Activity in progress"
    content:
      text/event-stream:
        anyOf:
          "event_in_progress":
            schema:
              $ref: "#/components/schemas/EventProgess"
          "event_completed":
            schema:
              $ref: "#/components/schemas/EventWithCompletionData"

This specifies event types, but is limited to JSON.

Specify content-type; specify event type

E.g. (again may not be idiomatic OpenAPI)

responses:
  "200":
    description: "Activity in progress"
    content:
      text/event-stream:
        anyOf:
          "event_in_progress":
            eventContentType: "application/json"
            schema:
              $ref: "#/components/schemas/EventProgess"
          "event_completed":
            eventContentType: "text/plain"
            schema:
              $ref: "#/components/schemas/EventWithCompletionData"

This is fully flexible, but probably has the downside of clients having to decide how to deal with different content types in messages!

[handrews]

@robertlagrant how is this different from any other API's typed messages? Even if SSE is the thing defining the type, the problem of designating a particular schema as a "type" (rather than a set of constraints with no additional meaning) is a common one for APIs. I don't see why SSE should get special handling over anyone else's type system.

[disintegrator]

Hi there, wanted to share that we (Speakeasy) added an SSE feature to our code generator driven through OpenAPI. We were able to describe this kind of API neatly without funky extensions with OpenAPI and JSON Schema. You can read about it here: https://www.speakeasy.com/docs/runtime/server-sent-events#modeling-sse-in-openapi

[kevinswiber]

@disintegrator Thanks for this! I believe contentMediaType and contentEncoding were added in JSON Schema draft-07 while contentSchema was added in 2019-09. I think this means the proposed solution will only work with the OpenAPI 3.1 release line. Is that right, @handrews?

[handrews]

@kevinswiber yes, 3.1 (and be sure to read the draft 2020-12 versions- these keywords took a bit to get the explanation right).

(speaking to folks in general) We really can't do anything about 3.0. The solution to 3.0 problems is 3.1.

[handrews]

@disintegrator ironically, those keywords get confusing around multipart because contentMediaType overlaps with the Encoding Object's contentType (Encoding Object wins), and contentEncoding at least in theory could also be handled by the Encoding Object's headers field with Content-Transfer-Encoding, which is actually deprecated for multipart/form-data anyway....

This is one of many reasons we want to offer a new, refactored system for non-JSON data modeling in 3.3 (too big of a feature for 3.2). It's just too many weird bits and pieces that don't entirely fit together right now.

[handrews]

To be clear: 3.2 and 3.3 will be strictly compatible with 3.1. The existing data modeling isn't going anywhere, but we can't keep putting endless duct tape on something that's gotten rather rickety already. As seen by needing to add a ton of new explanation in 3.0.4 and 3.1.1 to deal with confusion that people have faced.

[handrews]

(speaking to folks in general) We really can't do anything about 3.0. The solution to 3.0 problems is 3.1.

You know, I said this, but now that I think about it, since we're talking to people implementing tools... JSON Schema ignores unknown keywords, so you can just throw the content* keywords into a draft-04 schema if you want. You don't get annotation results so you'd have to associate them with the correct instance locations yourself (or internally run a tool like alterschema and convert it to 2020-12), but there's no reason you couldn't just build a tool that uses those keywords if present.

Although... hmm.. OAS 3.0's schema object requires the x- prefix, doesn't it... so you'd have to use x-contentMediaType , etc, 🤦 (have I mentioned lately how much I dislike the x- prefix requirement?)

Eh, just upgrade to 3.1 if possible!

[handrews]

@disintegrator I'm going to start a new thread here so that the previous one can keep going on contentMediaType or other smaller things.

It's clear that you put a lot of thought into this, and have proven its utility through implementation. That definitely carries weight.

However... TL;DR: You've done a great job of modeling the EventSource Web API (which I'll call ESW), but the OAS Media Type Object does not operate at that level. It only operates at the level of documents (even indefinite-length ones) based on the media type format (text/event-stream in isolation, not in the larger context of SSE).

---

I'll go into more detail here, but do also read the last bit after the next horizontal divider as I talk about some other possibilities.

SSE has both an application-level interface (ESW) and a wire-level interface (text/event-stream, and maybe some HTTP usage conventions — I can't make heads or tails of WHATWG specs because they're all written exclusively for browser implementors in pseudocode).

The OAS is only concerned with the wire-level interface. We do model data based on its in-memory, parsed form, so there is some distinction between that and the wire format, most notably for form data. But even there, the Media Type Object models documents (whether finite or indefinite) of a given media type. Hence the name.

The only place where we model at a different level is the Parameter Object, and that has generally been a source of pain that we hope to address in 3.3 (modeling application/x-www-form-urlencoded should look the same whether it is in a query string or a message body, among other inconveniences).

SSE as a whole, and ESW in particular, are among many higher-level protocols/APIs/conventions built on top of HTTP. Encapsulating such higher-level usage is a great thing for an SDK to do, but the OAS does not model any of these things, and it would be an enormous undertaking and expansion of scope to do so. On the other hand, AsyncAPI is much more about these sorts of higher interfaces. My impression is that AsyncAPI isn't about non-HTTP things, it's about async things, which might be implemented on HTTP or some other protocol. If you want to model events, that's AsyncAPI.

Getting back to the OAS perspective, the only new thing for us to model is documents of the text/event-stream media type. It's quite clear that the text/event-stream format is a sequence of sets of name-value pairs (the appearance of multiple data: fields for data that spans newlines is a serialization detail and irrelevant to the data modeling, just as OAS does not distinguish between multiple HTTP headers on separate lines or with comma-separated values).

So we really would model text/event-stream as an array, which would pretty much just involve taking your schema and stuffing it under an items keyword. We would leave it to a higher level change from the document view (a sequence of events grouped by whole or partial HTTP resposne) to an event view. This is the same approach we are taking for streaming JSON formats: While the stream is just a transport packaging format (you use the JSON documents in the stream, not the stream itself), application/json-seq, application/jsonl and application/x-ndjson are sequences of JSON documents, not JSON documents.

Media Type Objects need to model media types, not an application interface built on top of a media type.

---

That said if AsyncAPI is not suitable for SSE (and I really do not keep up with that project so I'm not clear on that point), someone could make a spec that sits on top of the OAS and describes a higher-level interface. The Arazzo workflows specificaton essentially does just that, and it is better as a separate spec than as part of the OAS.

We're only just starting to figure out how to build an ecosystem of API specs that work together to model what people need, preferably without a lot of redundancy. We would not want a system that requires modeling the low-level details of text/event-stream in order to re-state most of it in a more application-level form. So there would have to be some thought as to what would be suitable there.

[disintegrator]

You've done a great job of modeling the EventSource Web API (which I'll call ESW), but the OAS Media Type Object does not operate at that level. It only operates at the level of documents (even indefinite-length ones) based on the media type format (text/event-stream in isolation, not in the larger context of SSE).

Indeed, this is the kind of ambiguity I identified early and anticipated some guidance from the specification to come along after some time. Glad this is happening now!

I can also get behind the justification for using arrays. I admit I didn't have the same perspective as you or others working in this space but reading the explanation above made a lot of sense.

I'm also glad we got it almost right and it seems we only have a couple of small course corrections to make if your proposal described so far moves forward.

Thanks again!

[handrews]

I'm also glad we got it almost right and it seems we only have a couple of small course corrections to make if your proposal described so far moves forward.

Indeed- I'm pretty sure that the direction we'll go in is to formalize treating it as an array and using the content* keywords for things like JSON or other non-plain-text values, and using null for that [DONE] token. I'll open an issue for that, and we might be able to get it into 3.2.

[kevinswiber]

@disintegrator @handrews Thanks for having this discussion. I do think it's important for OAS to represent the text/event-stream media type. It's very common to use in conjunction with more traditional API media types. It's deliberately simple. Even though AsyncAPI can model SSE, I think there's a strong case for OpenAPI Specification to support it, as well, and take advantage of the benefits the authors provided us by keeping it simple. (WebSockets would be more difficult because of the sub-protocol, but that's a different discussion.)

[handrews]

@kevinswiber definitely agree that we should have text/event-stream support. It's only the higher-level EventSource Web API interface that I think is more AsyncAPI-esque.

We can also just state clearly that a schema of items: {anyOf: [...]} (or oneOf) indicates exactly the same thing that Speakeasy's current implementation (without the items part) does. If there are use cases for not treating it like that, we may want to figure out what the relationship is. But I think the only real change from what Speakeasy has is that the "official" solution would be more verbose and more flexible (because of the ability to have more embedded data formats than JSON)

[disintegrator]

Somewhat tangential but a few months ago we had a user that wanted to generate an SDK to consume an API that streamed lines of json. Each line represented a structured log message/event.
Instead of supporting this feature directly, we advised them to adopt text/event-stream which involved prepending each line with data: and an extra newline between each line. With encoding properties I think they would have ended with a nice, complete description of that endpoint.

I think solving this modelling problem out for SSE should unblock several other streaming HTTP API formats.

context here: speakeasy-api/speakeasy#832 (comment)

[kevinswiber]

One thing that occurs to me is that, even with text/event-stream, most of the time, we're looking to model a sub-protocol, even if SSE doesn't make that explicit like WebSockets does. We might be able to leverage prefixItems to validate a sequence of messages, but really, OAS isn't exactly equipped to model sub-protocols. Thoughts?