[API]: Stop order API should be a subscription

[JonRay15]

API Overview

In order to ... support more timely FE behaviour on stop orders We will build an API to... provide a the stop order API via subscription So that ... Console and wallet can provide better UX for users to see the result of their orders in toasts

Specs

Spec name to spec or section within a spec

API request details

• [ ] Make a stop order subscription
• [ ] Both a normal websocket stream and a GraphQL subscription
• [ ] For a normal orders subscription we also get a 'snapshot' emitted as the first event. While we don't rely on this on the frontend currently, it would be nice if we also had this for stop orders as we can make some optimizations using it.

Websocket

• Endpoint: api/v2/stream/stoporders
• Query parameters
  • marketIds: string[]
  • partyIds: string[]

GraphQL

type StopOrderUpdate {
  ... # Same as StopOrder where possible. Perhaps nested order field would need to change to orderId: ID!
}

type Subscription {
  stopOrders(
    filter: StopOrderFilter # Perhaps the liveOnly field is not applicable for the subspcription
  ): [StopOrderUpdate!]
}

Filtering requirements (inputs)

• [ ] All the same filters as the existing stop order API
• [ ] For graphql StopOrderFilter should be used
• [ ] For a raw websocket stream required queryParameters would be
  • marketIds: string[]
  • partyIds: string[]

Sample API output (optional)

Websocket stream

# Endpoint
wss://darling.network/api/v2/stream/stoporders?marketIds=foo&partyIds=bar

# Result
{
   result: {
     updates: {
       stoporders: [
         {
           id: "123",
           marketId: "foo",
           partyId: "bar",
           ...
         }
       ]
     }
   }
}

GraphQL

# Query
subscription StopOrders {
  stopOrders(filter: { marketIds: ['foo'], partyIds: ['bar'] }) {
    id
    marketId
    partyId
    status
  }
}

# Result
{
  data: {
    stopOrders: [
      { id: "123" , marketId: "foo", partyId: "bar", status: "STATUS_TRIGGERED" },
      { id: "345" , marketId: "foo", partyId: "bar", status: "STATUS_EXPIRED" }
    ]
  }
}

Questions

• Can the stop orders subscription also emit a snapshot event?
• Can we reuse the StopOrderFilter type? Is the liveOnly field applicable in StopOrderFilter?
• What fields can we have in StopOrderUpdate? Is order: Order problematic? Perhaps orderId: ID would be more consistent?

API test scenarios

Detailed scenarios that can be executed as feature tests to verify that the API has been implemented as expected.

GIVEN (setup/context) WHEN (action) THEN (assertion) For example... See here for more format information and examples.

Additional Details (optional)

Any additional information that provides context or gives information that will help us develop the feature.