GraphQL — Opsalis Learn

What Is GraphQL?

GraphQL is a query language for APIs and a runtime for executing those queries against your data. Developed internally at Facebook in 2012 and released publicly in 2015, GraphQL gives clients the power to ask for exactly the data they need — nothing more, nothing less. Unlike REST, where each endpoint returns a fixed data structure, GraphQL exposes a single endpoint and lets the client specify the shape of the response.

At the heart of every GraphQL API is a schema, written in the Schema Definition Language (SDL). The schema defines every type, field, and relationship your API supports. Types are strongly typed — String, Int, Float, Boolean, ID, plus custom object types, enums, interfaces, and unions. Clients can introspect the schema at runtime, discovering all available operations without reading external documentation.

GraphQL operations come in three flavors: queries (read data), mutations (write data), and subscriptions (real-time updates via WebSocket). Each field in the schema has a resolver — a function that fetches the actual data from your database, another API, or any other source. This means a single GraphQL query can aggregate data from multiple backends in one round trip.

The biggest advantage of GraphQL is solving the over-fetching and under-fetching problems. With REST, an endpoint might return 50 fields when you only need 3 (over-fetching), or you might need to call 5 different endpoints to assemble one screen of data (under-fetching). GraphQL eliminates both: one query, exactly the fields you need, one network round trip.

How GraphQL Works with Opsalis

If your API speaks GraphQL, the Opsalis handler knows how to work with it natively. Consumers still get a standard OpenAPI interface — the handler bridges the gap automatically.

Owner provides a GraphQL schema (SDL). Upload your .graphql schema file via the handler dashboard. The handler parses the types, queries, and mutations to understand your API surface.
Handler sends queries as POST requests with a JSON body containing { "query": "...", "variables": {...} }. When a consumer request arrives, the handler constructs the appropriate GraphQL query and sends it to your API.
Consumer still gets OpenAPI. The handler auto-converts your GraphQL schema into OpenAPI endpoints that consumers can call with simple REST-style requests. Consumers never need to learn GraphQL — the handler translates both directions.

No changes to your GraphQL server. Keep your existing schema, resolvers, and server configuration. The handler simply acts as a GraphQL client, sending queries and forwarding responses.

Demo API: NASA Exoplanet Archive

This demo uses the NASA Exoplanet Archive — a dataset of over 6,000 confirmed exoplanets discovered by missions like Kepler, TESS, and ground-based surveys. Query planets by name, host star, discovery method, orbital period, mass, radius, equilibrium temperature, and more. A scientifically rich dataset that showcases GraphQL's ability to navigate complex, nested data.

← Owner Guide

Code Example

Query exoplanets by discovery method

# GraphQL query via POST to the exoplanet API
curl http://localhost:4002/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ planets(discoveryMethod: \"Transit\", limit: 3) { name hostStar mass radius orbitalPeriod discoveryYear } }"
  }'

Response

{
  "data": {
    "planets": [
      {
        "name": "Kepler-22 b",
        "hostStar": "Kepler-22",
        "mass": null,
        "radius": 2.38,
        "orbitalPeriod": 289.86,
        "discoveryYear": 2011
      },
      ...
    ]
  }
}

Introspect the schema

# Discover all available types and fields
curl http://localhost:4002/graphql \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ __schema { types { name fields { name type { name } } } } }" }'

GraphQL at a Glance

Concept	Details
Transport	HTTP POST (typically), WebSocket for subscriptions
Data format	JSON
Spec format	Schema Definition Language (SDL / .graphql)
Operations	Query, Mutation, Subscription
Strongly typed	Yes — schema enforces types at runtime
Best for	Complex data graphs, mobile apps, aggregation layers