|
| 1 | +--- |
| 2 | +title: The Apollo Studio Explorer |
| 3 | +sidebar_title: The Explorer |
| 4 | +--- |
| 5 | + |
| 6 | +The Apollo Studio Explorer is a powerful web IDE for creating, running, and managing GraphQL operations: |
| 7 | + |
| 8 | +<iframe width="560" height="315" src="https://www.youtube.com/embed/j8b0Bda_TIw" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> |
| 9 | + |
| 10 | +The Explorer is free for all Apollo Studio organizations. It supports all GraphQL operation types (`Query`, `Mutation`, and `Subscription`). |
| 11 | + |
| 12 | +## Setup |
| 13 | + |
| 14 | +To get started with the Explorer, [create a graph](./getting-started/#2-create-your-first-graph) in Apollo Studio and then navigate to the graph's Explorer tab. |
| 15 | + |
| 16 | +The Getting Started tab _within_ the Explorer helps you get up and running with core features. |
| 17 | + |
| 18 | +When you execute your first query, the Explorer prompts you for the URL of your running GraphQL server. You can then change this URL at any time from the Explorer's Settings tab. |
| 19 | + |
| 20 | +## Building a query |
| 21 | + |
| 22 | +### The operation editor |
| 23 | + |
| 24 | +The Explorer’s operation editor is built on [Monaco](https://microsoft.github.io/monaco-editor/). It provides common features of query-building tools, including: |
| 25 | + |
| 26 | +* Panels for specifying headers and variables |
| 27 | +* Persistence across sessions |
| 28 | +* Keyboard shortcuts (click the keyboard icon in the bottom-right corner of the operation editor to view all available shortcuts) |
| 29 | + |
| 30 | +The editor also provides full IntelliSense support for GraphQL, including: |
| 31 | + |
| 32 | +* Query linting |
| 33 | +* Autocomplete |
| 34 | +* Peek definitions on mouse hover |
| 35 | +* Jump-to-definition with command-click |
| 36 | + |
| 37 | +The editor can manage multiple operations and reason about those operations individually. As you work, the editor shifts focus to whichever operation you click into. Each operation has its own context menu ("**...**") that enables you to format it, copy a link to share, or generate a `curl` command. |
| 38 | + |
| 39 | +### The Documentation tab |
| 40 | + |
| 41 | +The Explorer's Documentation tab enables you to step into your schema, beginning at one of its entry points. As you step into a field and its subfields, the Explorer keeps track of your current path within the schema. |
| 42 | + |
| 43 | +You can click the **⊕** button next to any field in the Documentation tab to add that field to the operation editor, at your current path. By default, the Explorer automatically generates variables for that field's arguments. |
| 44 | + |
| 45 | +## Searching your schema |
| 46 | + |
| 47 | +The Explorer provides a two-step schema search (shortcut `⌘+K`): |
| 48 | + |
| 49 | +1. Find the schema field you're looking for |
| 50 | +2. Find the ideal _path_ to that field from your schema's entry points |
| 51 | + |
| 52 | +### 1. Find a field |
| 53 | + |
| 54 | +First, you search for a field by its name (e.g., `email`). The interface helps you differentiate between fields with the same name (e.g., `User.email` versus `Organization.email`). The search is "fuzzy", so it works even if you don't know a field's exact spelling. |
| 55 | + |
| 56 | +If you know exactly which type and which field you're looking for, you can separate those values with a period (e.g., `User.email`). |
| 57 | + |
| 58 | +### 2. Find a path to the field |
| 59 | + |
| 60 | +After you identify a type-field pair, the Explorer lists all of the _paths_ to that field that start at your schema's entry points (`Query`, `Mutation` and `Subscription`). These paths are ordered by depth. |
| 61 | + |
| 62 | +> Finding the path to a field is particularly important with GraphQL, because you can only query a field if that field's position within your query is valid. |
| 63 | +
|
| 64 | +After you select which path you want, the Explorer opens that path in its Documentation tab. You can then click the **⊕** button to add that path to your query. |
| 65 | + |
| 66 | +## Additional features |
| 67 | + |
| 68 | +### Authentication |
| 69 | + |
| 70 | +The Explorer currently provides the following options for authentication. If your graph has authentication requirements that aren't covered by these options, please contact us at **[email protected]** with questions or feedback. |
| 71 | + |
| 72 | +#### Request headers |
| 73 | + |
| 74 | +The bottom of the Explorer editor provides a Headers section where you can set headers that are included in your operation's HTTP request. |
| 75 | + |
| 76 | +For example, you can provide a bearer token in an `Authentication` header like so: |
| 77 | + |
| 78 | +```json |
| 79 | +{ |
| 80 | + "Authentication": "bearer <TOKEN>" |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +> **Beta feature:** You can specify default headers that are applied to _every_ Explorer request executed by _every_ user in your organization. This can be useful if you want to provide a consistent identifier to your server for requests coming from the Explorer. To request access to this beta feature, please contact **[email protected]**. |
| 85 | +
|
| 86 | +#### Cookies |
| 87 | + |
| 88 | +If your graph authenticates using cookies, you can configure your endpoint to share those cookies with https://studio.apollographql.com. |
| 89 | + |
| 90 | +Once configured, requests sent from https://studio.apollographql.com will carry the cookies from your domain when you run queries with the Explorer. If you're logged in on your domain, requests from the Explorer will also be logged in. If you log out on your domain and the cookie is removed, requests from the Explorer will be logged out. |
| 91 | + |
| 92 | +To set this up, your [cookie's value must contain `SameSite=None; Secure`](https://www.chromium.org/updates/same-site). Additionally, these CORS headers must be present in your server's response to Studio: |
| 93 | + |
| 94 | +```bash |
| 95 | +Access-Control-Allow-Origin: https://studio.apollographql.com |
| 96 | +Access-Control-Allow-Credentials: true |
| 97 | +``` |
| 98 | + |
| 99 | +#### Preflight Scripts (beta) |
| 100 | + |
| 101 | +> To request access to preflight scripts, contact **[email protected]**. |
| 102 | +
|
| 103 | +[Similar to Postman](https://learning.postman.com/docs/writing-scripts/pre-request-scripts/), the Explorer can execute custom JavaScript before your request runs. This feature is especially useful for managing OAuth, for example by refreshing an access token automatically. |
| 104 | + |
| 105 | +You can save preflight scripts to your organization, meaning all users in your organization can use them. |
| 106 | + |
| 107 | +For more information, see the [documentation for preflight scripts](https://github.com/apollographql/apollo-studio-community/blob/main/preview-docs/PreRequestScripts.md). |
| 108 | + |
| 109 | +### Display |
| 110 | + |
| 111 | +#### Dark mode |
| 112 | + |
| 113 | +> Toggle between light and dark mode from the Explorer's Settings tab. |
| 114 | +
|
| 115 | +#### Table layout for response data |
| 116 | + |
| 117 | +> Toggle between table and JSON layout from the top of the Explorer's Response panel. |
| 118 | +
|
| 119 | +You can view an operation's response as JSON or as a table. Table layout is especially useful when your response includes an array, or when you want to share a query's results with someone who isn't familiar with JSON. |
| 120 | + |
| 121 | +#### Inline/Extract variables |
| 122 | + |
| 123 | +> Click the "**...**" menu next to an operation in the editor to select a notation for variables. |
| 124 | +
|
| 125 | +While editing your operations, you can toggle between inline or extracted notation for variables. This is useful when you want to switch notations to copy and paste something, or when you're drafting a query in the editor and want to move it to your code. |
| 126 | + |
| 127 | +##### Inline variable |
| 128 | + |
| 129 | +```graphql:title=query.graphql |
| 130 | +query { |
| 131 | + user(id: "Beth Harmon") { |
| 132 | + name |
| 133 | + } |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +##### Extracted variable |
| 138 | + |
| 139 | +```graphql:title=query.graphql |
| 140 | +query($id: ID!) { |
| 141 | + user(id: $id) { |
| 142 | + name |
| 143 | + } |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +```json:title=variables.json |
| 148 | +{ |
| 149 | + "id": "Beth Harmon" |
| 150 | +} |
| 151 | +``` |
| 152 | + |
| 153 | +### Federation |
| 154 | + |
| 155 | +#### Query plans for federated graphs |
| 156 | + |
| 157 | +If you're working with a federated graph in Studio, the Explorer dynamically calculates query plans for your operations in the right-jpanel (an option under the Responses tab). As you edit your query, the Explorer will recalculate your query plans and show you their updates. |
| 158 | + |
| 159 | + |
| 160 | + |
| 161 | +### Local development |
| 162 | + |
| 163 | +Unline similar GraphQL clients, the Explorer obtains your server's schema from Apollo Studio by default, _not_ by introspecting your server. This has the following benefits: |
| 164 | + |
| 165 | +* The Explorer can provide documentation and schema IntelliSense, even if your endpoint has disabled introspection (this is common for production graphs). |
| 166 | +* The Explorer can provide information about directives, which introspection does not support. |
| 167 | + |
| 168 | +You can still use the Explorer for local development. To do so, create a [development graph](https://studio.apollographql.com/dev) in Studio. |
| 169 | + |
| 170 | +A dev graph uses introspection to fetch your schema from your local endpoint, and it also polls regularly for changes. Whenever a new schema is detected, the dev graph pulls this change and updates itself automatically. You can also pause introspection polling at any time. |
| 171 | + |
| 172 | +### Networking |
| 173 | + |
| 174 | +#### CORS policies |
| 175 | + |
| 176 | +Requests from the Explorer go straight from your browser to your GraphQL server, so your endpoint will see requests coming from the `https://studio.apollographql.com` domain. |
| 177 | + |
| 178 | +It's common for public endpoints to have CORS policies that restrict which domains can query them. If your endpoint has CORS protections enabled, you probably need to safe-list https://studio.apollographql.com in your CORS policy to use the Explorer. |
| 179 | + |
| 180 | +If you can't change your CORS policy, you might be able to write a small proxy to your endpoint and point the Explorer to the proxy instead. CORS policies are enforced by browsers, and the proxy won't have the same issues communicating to your endpoint. |
| 181 | + |
| 182 | +### Saving operations |
| 183 | + |
| 184 | +#### Operation history |
| 185 | + |
| 186 | +> View your operation history from the Explorer's **Run history** tab. |
| 187 | +
|
| 188 | +The Explorer saves the history of your recently run operations (and the variable values for those operations) to your browser's local storage. Access your history to retain and recover previous work without cluttering your editor. |
| 189 | + |
| 190 | +#### Downloading responses |
| 191 | + |
| 192 | +You can copy responses from your operations with a button or download any given response to a local JSON file. |
| 193 | + |
| 194 | +### Testing operations |
| 195 | + |
| 196 | +#### Mocked responses |
| 197 | + |
| 198 | +> Enable **Mock responses** from the Explorer's Settings tab. |
| 199 | +
|
| 200 | +This feature naively mocks operation responses based on your schema's types, instead of sending your operations over the wire to your endpoint. |
| 201 | + |
| 202 | +Mocked responses are helpful if you want to get a feel for the shape of a query's response when your endpoint isn't available, or if you need a quick response to use in a code sample or a unit test. |
| 203 | + |
| 204 | +#### Response hints |
| 205 | + |
| 206 | +> Enable **Use response hints** from the Explorer's Settings tab. |
| 207 | +
|
| 208 | +As you build your query, the Explorer runs partial queries under the hood and shows their results in-line. This is helpful when you want to get a sense of the data you'll get back in your full operation response. It can also help you retrieve a quick answer to a query without needing to click the Run button. |
| 209 | + |
| 210 | +The Explorer does not show response hints for mutations (this requires running partial mutations, which is unsafe). |
| 211 | + |
| 212 | +#### Field latency hints |
| 213 | + |
| 214 | +As an alternative to [response hints](#response-hints), the Explorer can show you hints for the latency of the fields in your query. This option is available only if you've configured your graph to [report field usage and tracing data to Studio](./setup-analytics/). |
| 215 | + |
| 216 | +The Explorer shows you the 95th-percentile response times for the fields in your query to help you get a sense of how "expensive" your query is and what the bottlenecks in response time will be. |
| 217 | + |
| 218 | +#### `graphql-lodash` integration |
| 219 | + |
| 220 | +The Explorer [extends your schema with `graphql-lodash`](https://github.com/APIs-guru/graphql-lodash) on the client side, so you can write queries that include lodash directives and they will resolve correctly. This is helfpul if you want to manipulate your response data into into a specific format for exporting, or if you want to do some quick analysis without needing to export. |
| 221 | + |
| 222 | +Here's an example of a query that uses `graphql-lodash`. You can try pasting this in the Explorer embedded at http://apollographql.com/studio/develop: |
| 223 | + |
| 224 | +```graphql:title=example.graphql |
| 225 | +query StarWarsGenderStats { |
| 226 | + genderStats: allPeople @_(get: "edges") { |
| 227 | + edges @_(countBy: "node.gender") { |
| 228 | + node { |
| 229 | + gender |
| 230 | + } |
| 231 | + } |
| 232 | + } |
| 233 | +} |
| 234 | +``` |
| 235 | + |
| 236 | +## FAQ |
| 237 | + |
| 238 | +### Does the Explorer support subscription operations? |
| 239 | + |
| 240 | +Yes. You can run queries, mutations, and subscriptions all from the same Explorer page. You can start and stop listening to subscriptions, and you can see new subscription data as it comes in and old information as it becomes stale. |
| 241 | + |
| 242 | +You can also set your server's subscription websocket endpoint independently from the HTTP endpoint for queries and mutations. |
| 243 | + |
| 244 | +### Is the Explorer available for on-prem distribution? |
| 245 | + |
| 246 | +Not at this time. The Explorer is available for free, unlimited use in Apollo Studio, but it is not available for download or on-prem distribution. This might change in the future, but for now our goal is to provide the best possible Explorer experience from within Studio. |
| 247 | + |
| 248 | +### Do my Explorer operations pass through Apollo servers? |
| 249 | + |
| 250 | +No. Operations you run in the Explorer are sent directly from your browser to your GraphQL server, _without_ passing through Apollo's systems. Apollo never sees your request headers or response data. For more information, see [Apollo Studio data privacy and compliance](./data-privacy). |
0 commit comments