Get started

API / Cookbook / 04

Build a session view in one request

A session page needs four things: the session, its first turns, the machines and files they came from, and any attached artifacts. Over REST that is four calls. In GraphQL it is one.

GraphQLLive

Four reads, one round trip
actor app: Your app
actor gql: Tracez GraphQL
actor ops: Tracez operations
app -> gql: POST /graphql (4 aliased fields)
note gql: parse, bound to 500 nodes
gql -> ops: readSession
gql -> ops: readTurns
gql -> ops: readSources
gql -> ops: listArtifacts
ops --> gql: four Reply objects
gql --> app: one JSON response

Steps

  1. Write the query

    Aliases let you call several operations in one document. Every field takes a single input and returns a Reply.

    query SessionView($id: String!) {
  session:   readSession(input: { session_id: $id })   { http_status data error { code message } }
  turns:     readTurns(input:   { session_id: $id })   { data error { code } }
  sources:   readSources(input: { session_id: $id })   { data }
  artifacts: listArtifacts(input: { session: $id })    { data }
}

  2. Send it

    curl https://tracez.recurz.ai/graphql \
  -H "Authorization: Bearer $RECURZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"…","variables":{"id":"SESSION_ID"}}'

  3. Handle each field on its own

    A field that fails carries its own error and the rest still return data, so one missing artifact doesn't blank the page. data holds the same JSON the REST call returns, field names included.

    {"data":{
  "session": {"http_status":200,"data":{"session":{…}},"error":null},
  "turns":   {"data":{"items":[…],"has_more":true,"next_after":"1873"},"error":null},
  …
}}

  4. Load more turns

    When the reader scrolls, ask for readTurns(input: { session_id: $id, after: "1873" }) with the last next_after.

data is a JSON scalar today, so you select the envelope, not individual session fields. Queries are capped at 32 KB and 500 nodes.