You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
👋 Hi there! This guide walks you through integrating REST APIs into your graph using [Apollo Connectors](https://www.apollographql.com/docs/graphos/schema-design/connectors).
2
-
3
-
-[Setup](#setup)
4
-
-[Part two: Check out how Connectors work](#part-two-check-out-how-connectors-work)
5
-
-[Time to build your API](#time-to-build-your-api)
6
-
-[Debugging your schema](#debugging-your-schema)
7
-
-[Design your schema with Apollo’s IDE extensions](#design-your-schema-with-apollos-ide-extensions)
8
-
-[Check for errors each time you save](#check-for-errors-each-time-you-save)
9
-
-[Debug Connectors in Sandbox](#debug-connectors-in-sandbox)
1
+
2
+
-[Overview](#overview)
3
+
-[Designing your graph](#designing-your-graph)
4
+
-[IDE extensions for graph development](#ide-extensions-for-graph-development)
5
+
-[Working on your graph locally](#working-on-your-graph-locally)
6
+
-[The design process](#the-design-process)
7
+
-[Debugging Apollo Connectors](#debugging-apollo-connectors)
10
8
-[Publishing changes to GraphOS Studio](#publishing-changes-to-graphos-studio)
9
+
-[Deploying Apollo Router](#deploying-apollo-router)
11
10
-[Security](#security)
12
11
-[Additional resources](#additional-resources)
13
-
-[Deploying your graph](#deploying-your-graph)
14
-
-[More on graph development](#more-on-graph-development)
15
-
-[More about Connectors](#more-about-connectors)
16
-
17
-
# Setup
18
-
19
-
1. Open `products.graphql` to take a look at your graph's starter schema. Ignore the comments labeled with a ✏️ for now, we’ll get to them later.
20
-
2. In the terminal, run the `rover dev` command provided in the output of `rover init` under **Next steps**. The `dev` command starts a local development session and gives you access to Apollo Sandbox—a local, in-browser GraphQL playground, where you can run GraphQL operations and test your API as you design it.
21
-
3. In Sandbox, paste the following GraphQL query in the **Operation** section:
22
-
23
-
```
24
-
query GetProducts {
25
-
products {
26
-
id
27
-
name
28
-
description
29
-
}
30
-
}
31
-
```
32
-
33
-
4. Click `► GetProducts` to run the request. You'll get a response back with data for the product's id, name, and description; exactly the properties you asked for in the query! 🎉
34
-
35
-
## Part two: Check out how Connectors work
36
-
37
-
1. Let's find out where this data is coming from. Click the arrow next to **Response** and select the **Connectors Debugger** option.
38
-
2. Now, click the most recent request to review its details. In the **Request overview** tab, press the **cURL** button to copy the underlying HTTP request made to the REST API.
39
-
3. Run this request in your terminal and compare it with what’s been configured using the `@connect` directive in `products.graphql`. You'll notice that some properties in the terminal response match to the `selection` mapping in the schema. This is the key to how Connectors work!
40
-
41
-
Hooray! You ran a query, got some data back, and reviewed what Connectors are like under the hood! Feel free to experiment some more–try tweaking the query to see what data you can retrieve. 🚀
12
+
-[Graph development](#graph-development)
13
+
-[Connectors](#connectors)
14
+
-[Apollo Router](#apollo-router)
42
15
43
-
# Time to build your API
44
16
45
-
You’re all set to start building. You'll be working primarily with the `products.graphql` file.
17
+
# Overview
46
18
47
-
First, make sure you’ve installed and configured [your IDE extension of choice](https://www.apollographql.com/docs/graphos/schema-design/ide-support) so you can rely on its autocompletion, schema information, and syntax highlighting features.
19
+
👋 Hi there!
48
20
49
-
Then, follow the development cycle below:
21
+
Your new graph is set up with [Apollo Federation](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/federation). This means it’s built to grow, even if you’re starting with just one service. Right now, that service is defined in `products.graphql`, and you can treat it like a regular GraphQL API as you build it out.
50
22
51
-
1.[Add your REST API details using @source](https://www.apollographql.com/docs/graphos/schema-design/connectors/directives#source).
52
-
2. Define the types and fields you want your GraphQL API to expose. Use the inline comments labeled with a ✏️ to follow along.
53
-
3.[Configure the Connector's request details](https://www.apollographql.com/docs/graphos/schema-design/connectors/requests).
54
-
4.[Configure the Connector's response mapping](https://www.apollographql.com/docs/graphos/schema-design/connectors/responses). You can use the [Connectors Mapping Playground](https://www.apollographql.com/connectors-mapping-playground) to help convert JSON responses to and from GraphQL types.
55
-
5. Run operations and debug your API following the instructions in the section below.
23
+
This project is also set up to use [Apollo Router](https://www.apollographql.com/docs/graphos/routing) as the entry point for all requests to your graph. It’s a great way to get features like tracing, metrics, and caching out of the box. It gives you a single place to configure settings for your graph, like traffic shaping, authorization, and more. For now, the router simply forwards requests to your service, but as your graph grows, it can pull data from multiple places and return one clear, consistent result.
56
24
57
-
📓 **Note:** If you’re working with APIs that require headers, you’ll need to include them in `products.graphql` and add a router configuration file (`router.yaml`) to your project directory.
25
+
Finally, this graph also uses [Apollo Connectors](https://www.apollographql.com/docs/graphos/connectors), which let you integrate REST APIs directly into your GraphQL schema without writing any resolver code or deploying a backend GraphQL server. Instead of building separate services to connect your APIs, you simply add declarative directives such as `@connect` and `@source`to your schema, and Apollo Router automatically handles the REST API calls and data transformation for you.
58
26
59
-
To learn more about headers and other advanced features like configuring environment variables, telemetry, and authentication, visit [Apollo’s docs on working with Router](https://community.apollographql.com/c/graph-os/getting-started/35).
27
+
# Designing your graph
60
28
61
-
ℹ️ **Tip:** If you run into any issues or difficulties, please reach out via the [Apollo Community](https://community.apollographql.com/c/graph-os/getting-started/35). Click **New Topic** to start a discussion–the Apollo team is here to help!
29
+
## IDE extensions for graph development
62
30
63
-
# Debugging your schema
31
+
[Apollo’s IDE extensions](https://www.apollographql.com/docs/ide-support) are designed to help you catch and correct any issues related to schema design as early as possible. Lean on their instant feedback and autocomplete capabilities to help you create the types, fields, arguments, and connectors.
64
32
65
-
The Apollo dev toolkit includes a few debugging tools to help you design and develop your graph. The journey looks a little something like this:
33
+
## Working on your graph locally
66
34
67
-
1. Design your schema with Apollo’s IDE extensions
68
-
2. Check for errors each time you save
69
-
3. Debug Connectors in Sandbox
70
-
4. Rinse and repeat until you're happy with your API!
35
+
After completing the `rover init` flow, run the command you see in your terminal under **Next steps** (it will start with your `APOLLO_KEY`). This allows you to work with Apollo Router locally, giving you a way to design and test your supergraph in a safe environment, without the need to deploy anything yet.
71
36
72
-
## Design your schema with Apollo’s IDE extensions
37
+
You’ll get automatic [build checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks#build-checks-1), so you can identify issues early and make sure your services work together. It’s a fast way to iterate with confidence before going live.
73
38
74
-
Apollo’s IDE extensions are designed to help you catch and correct any issues related to schema design as early as possible. Lean on their instant feedback and autocomplete capabilities to help you create types, fields, arguments, and Connectors.
39
+
Once you run the command, the CLI will start watching your files for updates. Every time you make a change, Rover checks to see if the schema is valid. You can think of it as “hot-reloading” for your GraphQL schema. [More details about the dev command](https://www.apollographql.com/docs/rover/commands/dev).
75
40
76
-
## Check for errors each time you save
41
+
## The design process
77
42
78
-
When you run `rover dev`, Rover starts watching your files for updates. Every time you make a change, Rover checks to see if the schema is valid. You can think of it as “hot-reloading” for your GraphQL schema. [More details about the dev command](https://www.apollographql.com/docs/rover/commands/dev).
43
+
The best way to get started with schema design is to check out the different [schema types](https://www.apollographql.com/docs/graphos/schema-design) that make up your graph. You can also go straight to Apollo’s schema design guides, starting with [Demand-Oriented Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/demand-oriented-schema-design).
79
44
80
-
## Debug Connectors in Sandbox
45
+
## Debugging Apollo Connectors
81
46
82
47
83
48
84
-
In Apollo Sandbox, you can access the Connectors Debugger by selecting it from the **Response** drop-down on the right side of your screen. The debugger will provide detailed insights into network calls, including response bodies, errors, and connector-related syntax. You can also visit Apollo's docs to [learn more about troubleshooting Connectors](https://www.apollographql.com/docs/graphos/schema-design/connectors/troubleshooting#return-debug-info-in-graphql-responses).
49
+
In Apollo Sandbox, you can access the Connectors Debugger by selecting it from the Response drop-down on the right side of your screen. The debugger will provide detailed insights into network calls, including response bodies, errors, and connector-related syntax. You can also visit Apollo's docs to [learn more about troubleshooting Connectors](https://www.apollographql.com/docs/graphos/schema-design/connectors/troubleshooting#return-debug-info-in-graphql-responses).
85
50
86
51
# Publishing changes to GraphOS Studio
87
52
88
-
When you publish a schema to GraphOS, it becomes part of your schema’s version history and is available for checks, composition, and collaboration. When you run `rover init`, GraphOS takes care of your first publish for you.
53
+
Publishing your graph saves your schema to the GraphOS registry, allowing you to track its evolution and collaborate smoothly with your team when needed. GraphOS handles your first publish for you during `init`and creates an environment (or graph variant) called `current`, but any subsequent changes you make will require additional publishes.
89
54
90
-
Once you’ve made changes to your schema files and are happy with the state of your API, or if you’d like to test the experience of publishing schema changes to GraphOS Studio, paste and run the following command in your terminal:
55
+
Once you're happy with the state of your graph, replace the placeholder items in this command with your own and run it:
91
56
92
57
```
93
-
rover subgraph publish your-graph-id@main \ # Replace this with your `APOLLO_GRAPH_REF` value
58
+
rover subgraph publish your-graph-id@current \ # Replace this with your APOLLO_GRAPH_REF value
94
59
--schema "./products.graphql" \
95
-
--name products-subgraph \
96
-
--routing-url "https://my-running-subgraph.com/api" # If you don't have a running API yet, you can replace this with http://localhost:4000
60
+
--name products \
97
61
```
98
62
99
-
📓 **Note:** For production-ready APIs, [integrating Rover into your CI/CD](https://www.apollographql.com/docs/rover/ci-cd) ensures schema validation, reduces the risk of breaking changes, and improves collaboration.
63
+
**📓 Note:** The `rover subgraph publish` command usually includes a `--routing-url` flag, which is only required during your first publish or any time you want to change your routing URL. Otherwise, this flag can be left out. [Review other command options](https://www.apollographql.com/docs/rover/commands/subgraphs#publishing-a-subgraph-schema-to-graphos).
64
+
65
+
# Deploying Apollo Router
66
+
67
+
For your supergraph to work, two things must be true:
68
+
69
+
**The Apollo Router must be deployed.** The Router is what makes your graph live. It connects to GraphOS to fetch your published schema and serves a single GraphQL endpoint for your clients. It handles the work of calling the right subgraphs and combining their results behind the scenes.
70
+
71
+
**Each service needs to be reachable by the router.** When working with Apollo Connectors, your services become reachable via the REST API(s) you bring into your schema(s).
72
+
73
+
If you already know how to deploy and host the router, excellent! If you’d like some guidance for this step, [head over to Studio](https://studio.apollographql.com/) to set your endpoint and review deployment options.
100
74
101
75
# Security
102
76
@@ -105,23 +79,19 @@ For a more secure and reliable API, Apollo recommends updating your CORS policy
105
79
- Specifying which origins, HTTP methods, and headers are allowed to interact with your API
106
80
- Turning off GraphQL introspection to limit the exposure of your API schema
107
81
108
-
Making these updates helps safeguard your API against common vulnerabilities and unauthorized access. To learn more, [review Apollo’s documentation on Graph Security](https://www.apollographql.com/docs/graphos/platform/security/overview).
82
+
Making these updates helps safeguard your API against common vulnerabilities and unauthorized access. To learn more, check out [Apollo’s documentation on Graph Security](https://www.apollographql.com/docs/graphos/platform/security/overview).
109
83
110
84
# Additional resources
111
85
112
-
## Deploying your graph
113
-
114
-
-[Supergraph routing with GraphOS Router](https://www.apollographql.com/docs/graphos/routing/about-router)
Copy file name to clipboardExpand all lines: start-with-rest/supergraph.yaml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# A "supergraph" is a unified GraphQL API composed of different services known as "subgraphs"
2
2
3
3
# Set the maximum Apollo Federation version that subgraphs in this supergraph can use. Lean more at 🔗 https://www.apollographql.com/docs/graphos/schema-design/connectors/directives#prerequisites
4
-
federation_version: =2.10.0
4
+
federation_version: =2.11.0
5
5
subgraphs: # Use this section to add all of the services that make up your supergraph
6
6
products: # Your first subgraph has been named `products`
7
7
routing_url: http://placeholder # This value is unused but cannot be empty
0 commit comments