Server push of responses

HTTP/2 RFC 7540 introduced the concept of server push. This allows a server to pre-emptively send (or “push”) responses to a client in association with a previous client-initiated request.

From an API perspective, it provides an interesting way of implementing the Observer pattern in which a client issues a request indicating interest in changes in an object’s state, and the notifications of the changes are delivered as pushed responses.

An alternative way of delivering notifications is proposed in #716, #735, #736 and #737. The callback/webhook pattern is widely used and would be a valuable addition to the specification.

Server push offers a method of delivering notifications from server to client in which the connection is initiated by the client. The client does not need to listen for connections from the server, and there is no need for the server to hold credentials for connecting to the client because it does not initiate connections.

A push section is added to the operation object. This contains a list of possible push responses. Upon receipt of a request for an operation, the server may push one or more push responses prior to sending the final response for the operation.

An example below illustrates the concept.

paths:
  /consumer:
    post:
      description: Create a consumer and start delivering messages
      parameters:
      - name: CreateConsumerRequest
        in: body
        required: true
        schema:
          $ref: '#/definitions/CreateConsumerRequest'
      responses:
        200:
          description: Success
      push:
        /event:
          responses:
            200:
              description: Event pushed to consumer
              schema:
                $ref: '#/defintions/Event'
              headers:
                offset:
                  description: Offset of this event
                  type: integer
definitions:
  Event:
   anyOf:
   - $ref: '#/definitions/EventType1'
   - $ref: '#/definitions/EventType2'

The push object holds a list of Push Item Objects.

The Push Item Object contains a Push Path Object.

Field Pattern	Type	Description
/{path}	Push Path Object	A path for the pushed response.

The Push Path Object describes the responses.

Field Name	Type	Description
responses	Responses Object	Required. The list of possible responses.

Pushed responses are just like regular responses of an operation.

[sarnowski]

I would like to throw in gRPC that makes streaming (also bidirectional) first class definitions:

gRPC Concepts / RPC Lifecycle

Server streaming RPC

A server-streaming RPC is similar to our simple example, except the server sends back a stream of > responses after getting the client’s request message. After sending back all its responses, the server’s status details (status code and optional status message) and optional trailing metadata are sent back to complete on the server side. The client completes once it has all the server’s responses.

Client streaming RPC

A client-streaming RPC is also similar to our simple example, except the client sends a stream of requests to the server instead of a single request. The server sends back a single response, typically but not necessarily after it has received all the client’s requests, along with its status details and optional trailing metadata.

Bidirectional streaming RPC

In a bidirectional streaming RPC, again the call is initiated by the client calling the method and the server receiving the client metadata, method name, and deadline. Again the server can choose to send back its initial metadata or wait for the client to start sending requests.

What happens next depends on the application, as the client and server can read and write in any order - the streams operate completely independently. So, for example, the server could wait until it has received all the client’s messages before writing its responses, or the server and client could “ping-pong”: the server gets a request, then sends back a response, then the client sends another request based on the response, and so on.

This concept is very powerful and uses HTTP 2 to its full extend to get rid of all the hacks with long polling or all the complexities with context-loosing webhooks.

[itsjamie]

@AndrewJSchofield outside of HTTP/2 Server Push, there is also Server Sent Events.

This is similar to WebSockets, but works with a regular HTTP request, and is also possible to support resumption via the “ID” field.