GraphQL APIs
Your API's GraphQL endpoint on a local address. Queries only, checked against the schema, with every leaf of the data faked.
Start it
A source in sosie.yml: its upstream is the endpoint, and credentials work as for REST, in
its headers.
sources:
graph:
upstream: ${GRAPH_URL}
headers:
Authorization: Bearer ${GRAPH_TOKEN}
export GRAPH_URL='https://api.internal/graphql'
export GRAPH_TOKEN="$(cat ~/.config/graph.token)"
npx @sosie/cli
✓ graph api.internal/graphql, read-only: 31 types, 12 queries
✓ Every value is faked
graph: http://localhost:7674/graphql
Sosie serves GraphQL at the API’s own path, by GET and POST, batches included.
Which endpoints
An http(s) URL with a graphql or graphql.json segment in its path is GraphQL’s (/mygraphql is not):
| Endpoint | Example |
|---|---|
/graphql |
Most servers |
/v1/graphql |
Hasura |
/graphql/v1 |
Supabase |
/admin/api/…/graphql.json |
Shopify |
An endpoint at another path, such as gqlgen’s /query, is GraphQL with kind: graphql in its source.
Without it, the URL goes to the REST source. Sosie never sends a POST to find out: on a REST API, it could write.
The schema
By introspection, with Sosie’s credentials, at start-up. An API with introspection off is read from the
source’s schema: its SDL, or an introspection result as JSON, in a file or at a URL. A URL at the API’s own origin is
read with the source’s headers, and Sosie follows no redirect from it; one elsewhere is read without them.
- Each object and interface type is an entity; each field that holds a scalar or an enum is a field.
- Custom scalars map by name:
DateTime,Date,UUID,JSON,BigIntand the like.EmailandEmailAddresspick the email format,URLandURIthe URL format. - A field
idis the type’s key; one nameduserIdshares the values ofUser.id.
Clients’ introspection is answered from the schema Sosie holds, and never reaches the API. So clients can introspect an API that has introspection off.
The guard
- Queries only. A mutation or a subscription is refused, and its text never leaves Sosie. So is a field of the mutation type asked for under a query field.
- Checked first. Each operation is parsed and checked against the schema, and its variables against their types,
before anything goes upstream. What fails gets
400, quoting only what the client sent. - Bounded. A
POSTof up to 1 MB, batches of up to 50 operations, queries of up to 10,000 tokens. Checking runs on two threads of Sosie’s own, each query within 2 seconds and 256 MB, so a query built to be costly is refused (SOSIE_TOO_COSTLY) instead of stalling everyone else. - Only what runs. Only the operation to run, with the fragments it uses and the variables it declares, reaches the
API. A persisted query without its text is refused, and a
POSTis never redirected.
A query field that writes, other than a field of the mutation type, is the API’s to guard.
Faking
Every leaf of data is faked by the schema field it is, through aliases, fragments and nested objects, so
order.user.id, order.userId and user.id are one fake, and a person’s email is the database’s fake.
- An object of an interface or a union is faked by its own type: Sosie asks for its
__typenameunder an alias the client never sees. - A list keeps its first
max-rowsitems;extensions.sosiesays the rest were cut. - An integer beyond 2^53 keeps its digits, so its fake leads back to its record.
Errors. Since Sosie checked the query itself, anything the API says beyond that may quote data. Every message is
replaced by Sosie’s; an error’s path and a code such as FORBIDDEN or ORDER_NOT_FOUND are kept, and a code with
data in it is dropped.
Query by what you saw
Each argument, and each variable where it is used, is looked up in the field it names on the type its field returns:
user(id:) in User.id, users(email:) in User.email, orders(userId:) in User.id. Inside input objects too,
where an operator (where: { id: { _eq: 8 } }) compares with the field around it. A number that names no field
(first: 10) stays as written.
query { user(id: "87") { email orders { total } } }
Limits
- A JSON scalar’s keys that look like words (
{ "jdoe": … }) stay, as a json column’s do. - The schema, its descriptions included, is visible: it is the API, not its data.
- A variable sent as a JSON number beyond 2^53 is rounded as JavaScript reads it: send a 64-bit id as a string, or write it in the query.
@deferand@streamanswers, which come in parts, are not read yet.