See beyond POST /graphql

A network log organized only by path can make an entire GraphQL API look like one operation. In practice, the same endpoint can handle a navigation query, a search, an account lookup and a mutation.

apispy discriminates operations from the request body and separates batched requests. The captured variables and returned data describe each operation individually. The OpenAPI export also records the real endpoint alongside its synthetic operation paths.

How to reconstruct the schema

  1. Open the site in the analysis browser. Use its normal interface to trigger GraphQL requests.
  2. Explore several workflows. Navigation, search and detail pages may request different fields from the same types.
  3. Select the GraphQL host. Inspect distinct operations and then open the GraphQL view.
  4. Review and export the SDL. Check the reconstructed types and use Copy or Export to take the schema into your own workflow.

Type names from the actual responses

GraphQL responses can include __typename, which identifies the concrete object type. apispy uses those values rather than inventing object names from field paths. Repeated observations contribute fields to the same type, and several concrete types observed in one position can produce a union.

Illustrative reconstructed SDL
type Query {
  viewer: User
  projects: [Project!]
}

type User {
  id: ID!
  displayName: String
}

type Project {
  id: ID!
  name: String!
}

Each host receives its own reconstructed schema. Types from unrelated APIs are kept separate because the same type name can mean different things in different APIs.

When the client sends persisted queries

Some clients send a persisted query hash instead of the full GraphQL query text. Reconstructing types only by parsing request documents cannot recover a document that was never transmitted.

apispy also works from returned data and its type names. It can therefore reconstruct observed response types when a client uses persisted queries. Operation names and available query metadata still determine how much can be learned about the operations themselves.

What reconstruction cannot tell you

An object without __typename remains an opaque JSON scalar rather than an invented named type. Unrequested fields and unexercised arguments are not recoverable from the capture.

Nullability is observational: an exclamation mark means no null was seen in that position. It does not prove the server promises a non-null value in every case. The result is not a substitute for an authoritative server schema.

Read the GraphQL specification on type-name introspection for the role of __typename. Use OpenAPI exports for the corresponding HTTP operation documentation.

Product behavior described here reflects apispy v0.1. Inferred documentation depends on the traffic you observe.