GraphQL Request

GraphQL requests work over HTTP just like REST, but instead of defining multiple endpoints, you typically interact with a single endpoint (e.g., /graphql) and specify the exact data you want. This gives you flexibility, reduces over-fetching, and makes debugging APIs much simpler.

​

Create your first GraphQL request

​

Create a GraphQL request with multiple queries

​

Attach a schema from a file or URL

By default a GraphQL request builds its schema by introspecting whatever endpoint is in the URL bar, and that keeps working exactly as before. Attach a schema document yourself when introspection is turned off on the server, when the schema you develop against is not the one that endpoint serves yet, or when you keep the schema in your repository. The tab gives you three ways to get a schema, and they are mutually exclusive. Attaching a document turns introspection off for that request, and choosing Use GraphQL introspection drops the attached document. One request never has two live schema sources. Nothing is ever copied. Every attachment is a reference that Requestly re-reads when the request loads, so the schema document itself is never stored inside your request.

​

Attach a file from your machine

A file attachment stays a live reference, not a snapshot. Edit the file in your editor, click the refresh button beside the picker, and the change is picked up without attaching the file again. Requestly never watches the file, so picking up an edit is always an explicit refresh.

​

Attach a schema by URL

The URL you paste is meant to point at a schema document: GraphQL SDL, or the JSON result of an introspection query. Requestly fetches it and reads the response as a document first. If what comes back is not a schema document, Requestly then introspects that same URL before it reports any error. So pasting a plain GraphQL endpoint works too, and you do not need to know in advance which of the two a URL is. One thing to expect when the fallback is what succeeded: no document was ever parsed, so the request is now introspecting that URL rather than holding a document, and the tab says so. It reads “No schema document attached. This request uses GraphQL introspection” even though the schema loaded and is driving the editor. The URL is still added to the picker, so you can reuse it on another request.

​

Reuse a location you have attached before

Once a file or URL has loaded successfully, it is remembered on that device and offered in the picker on every other GraphQL request, with no network call. A document that failed to load is not remembered, so a broken location never comes back to haunt you. Each remembered row is labelled with a short name derived from its location, so the list stays one line per entry. Hover a row to see the full location. Hover any remembered row except the one this request is using and click the cross to forget it. Forgetting a location removes it from the list and nothing else: every request already attached to it stays attached and keeps working.

​

Go back to introspection

While a document is attached, the tab offers Use GraphQL introspection. Choosing it detaches the document and the request goes back to introspecting the URL in the URL bar. The control needs a request URL to work against, and says so when the URL bar is empty. While introspection is already the live source there is nothing to switch to, so the tab shows “Using GraphQL introspection” with its own re-run control instead.

​

What a teammate on another machine sees

What travels with a shared request depends on the kind of attachment, and not on whether you work in a team project or a local project. The behaviour is the same in both. If you want a schema to be shared, attach it by URL.

​

On a GraphQL example

A GraphQL example has a Schema tab too, and it shows where its parent request’s schema comes from rather than the schema itself: the source (Introspection, Schema document, or Local file), the location when that source is a URL, and that it was resolved from the parent request. Everything there is read-only, with no attach, reuse or refresh controls, because an example never carries a schema of its own. A Local file source shows no location at all, so an example never displays a path from another machine.

​

Why there is no “Import as specification”

Postman lets you import a GraphQL schema as an API specification. Requestly has no equivalent, and that is deliberate rather than an oversight: Requestly specifications have no GraphQL format for a schema to become. To share a schema with your team, host it where your teammates can reach it and attach it by URL. A URL attachment travels with the request. A file you attach stays on your own machine by design, and there is no way to promote it into something shared.

​

What survives when you attach SDL

An attached SDL document is used as SDL. Requestly never converts it to introspection JSON on the way in, so things introspection cannot express survive attaching: custom directive applications, and type extensions that add nothing but a directive.

​

When something goes wrong

Errors on this tab are short and always name what to do next. The common ones: If an attached file has moved, been deleted, or the browser has dropped its permission, the tab says so and offers Re-attach so you can point at it again in one click. The attach controls stay available in every error state, so you can fix the problem from where you are told about it.

​

What’s Next?