From 628fbb75a19093958e4714844e19ca95bd59fdad Mon Sep 17 00:00:00 2001 From: Trevor Blades Date: Mon, 14 Mar 2022 20:53:10 -0700 Subject: [PATCH] Updates for new docs infra (v2) (#6210) * Prepare v2 server docs for new infra * Update code fences * Use a relative link * Add algolia filters --- docs/source/api/apollo-server.md | 3 +- docs/source/api/graphql-tools.md | 3 +- docs/source/api/plugin/inline-trace.md | 1 - docs/source/api/plugin/schema-reporting.md | 1 - docs/source/api/plugin/usage-reporting.md | 1 - docs/source/config.json | 75 ++++++++++++++++++++++ docs/source/data/data-sources.mdx | 12 ++-- docs/source/data/errors.mdx | 16 ++--- docs/source/data/resolvers.mdx | 12 ++-- docs/source/data/subscriptions.mdx | 10 ++- docs/source/deployment/azure-functions.md | 1 - docs/source/deployment/gcp-functions.mdx | 13 ++-- docs/source/deployment/heroku.md | 1 - docs/source/deployment/index.md | 1 - docs/source/deployment/lambda.md | 1 - docs/source/deployment/netlify.md | 1 - docs/source/getting-started.mdx | 19 ++---- docs/source/index.mdx | 4 +- docs/source/installing-graphql-tools.md | 4 +- docs/source/integrations/middleware.md | 1 - docs/source/integrations/plugins.md | 8 +-- docs/source/migration-two-dot.md | 4 +- docs/source/monitoring/health-checks.md | 4 +- docs/source/monitoring/metrics.md | 2 +- docs/source/performance/apq.md | 4 +- docs/source/performance/caching.md | 11 ++-- docs/source/proxy-configuration.md | 2 +- docs/source/schema/creating-directives.mdx | 12 ++-- docs/source/schema/custom-scalars.md | 4 +- docs/source/schema/directives.md | 7 +- docs/source/schema/schema.md | 2 +- docs/source/schema/unions-interfaces.md | 4 +- docs/source/security/authentication.md | 1 - docs/source/security/terminating-ssl.md | 2 +- docs/source/testing/graphql-playground.mdx | 15 ++--- docs/source/testing/mocking.md | 2 +- docs/source/why-apollo-server.md | 4 +- 37 files changed, 150 insertions(+), 118 deletions(-) create mode 100644 docs/source/config.json diff --git a/docs/source/api/apollo-server.md b/docs/source/api/apollo-server.md index c731f362aef..75084f9d626 100644 --- a/docs/source/api/apollo-server.md +++ b/docs/source/api/apollo-server.md @@ -1,6 +1,5 @@ --- title: "API Reference: apollo-server" -sidebar_title: apollo-server api_reference: true --- @@ -8,7 +7,7 @@ This API reference documents the exports from the `apollo-server` package. ## `class ApolloServer` -The core of an Apollo Server implementation. For an example, see [Get started with Apollo Server](/getting-started/). +The core of an Apollo Server implementation. For an example, see [Get started with Apollo Server](../getting-started/). ### Methods diff --git a/docs/source/api/graphql-tools.md b/docs/source/api/graphql-tools.md index 8590833960b..2ca6c7fb01f 100644 --- a/docs/source/api/graphql-tools.md +++ b/docs/source/api/graphql-tools.md @@ -1,6 +1,5 @@ --- title: "API Reference: graphql-tools" -sidebar_title: graphql-tools --- The `graphql-tools` library enables the creation and manipulation of GraphQL schema. Apollo Server is able to accept a `schema` that has been enabled by `graphql-tools`. Apollo server directly exports all the function from `graphql-tools`, enabling a migration path for more complicated use cases. @@ -63,7 +62,7 @@ const jsSchema = makeExecutableSchema({ - `typeDefs` is a required argument and should be a GraphQL schema language string or array of GraphQL schema language strings or a function that takes no arguments and returns an array of GraphQL schema language strings. The order of the strings in the array is not important, but it must include a schema definition. -- `resolvers` is an optional argument _(empty object by default)_ and should be an object that follows the pattern explained in the [resolvers documentation](/data/resolvers/). +- `resolvers` is an optional argument _(empty object by default)_ and should be an object that follows the pattern explained in the [resolvers documentation](../data/resolvers/). - `logger` is an optional argument, which can be used to print errors to the server console that are usually swallowed by GraphQL. The `logger` argument should be an object with a `log` function, eg. `const logger = { log: e => console.log(e) }` diff --git a/docs/source/api/plugin/inline-trace.md b/docs/source/api/plugin/inline-trace.md index 809e91fac64..f229a544b62 100644 --- a/docs/source/api/plugin/inline-trace.md +++ b/docs/source/api/plugin/inline-trace.md @@ -1,6 +1,5 @@ --- title: "API Reference: Inline trace plugin" -sidebar_title: Inline trace plugin api_reference: true --- diff --git a/docs/source/api/plugin/schema-reporting.md b/docs/source/api/plugin/schema-reporting.md index 62c5594ac5c..28155c34614 100644 --- a/docs/source/api/plugin/schema-reporting.md +++ b/docs/source/api/plugin/schema-reporting.md @@ -1,6 +1,5 @@ --- title: "API Reference: Schema reporting plugin" -sidebar_title: Schema reporting plugin api_reference: true --- diff --git a/docs/source/api/plugin/usage-reporting.md b/docs/source/api/plugin/usage-reporting.md index 4603591ac9c..e0b4911d321 100644 --- a/docs/source/api/plugin/usage-reporting.md +++ b/docs/source/api/plugin/usage-reporting.md @@ -1,6 +1,5 @@ --- title: "API Reference: Usage reporting plugin" -sidebar_title: Usage reporting plugin api_reference: true --- diff --git a/docs/source/config.json b/docs/source/config.json new file mode 100644 index 00000000000..c95106aca89 --- /dev/null +++ b/docs/source/config.json @@ -0,0 +1,75 @@ +{ + "title": "Apollo Server", + "version": "v2", + "algoliaFilters": [ + "docset:server", + [ + "docset:react", + "docset:federation" + ] + ], + "sidebar": { + "Introduction": "/", + "Get started": "/getting-started", + "Changelog": "https://github.com/apollographql/apollo-server/blob/main/CHANGELOG.md", + "Apollo Federation": "https://www.apollographql.com/docs/federation/", + "Defining a Schema": { + "Schema basics": "/schema/schema", + "Unions and interfaces": "/schema/unions-interfaces", + "Custom scalars": "/schema/custom-scalars", + "Directives": "/schema/directives", + "Creating directives": "/schema/creating-directives" + }, + "Fetching Data": { + "Resolvers": "/data/resolvers", + "Data sources": "/data/data-sources", + "Error handling": "/data/errors", + "File uploads": "/data/file-uploads", + "Subscriptions": "/data/subscriptions" + }, + "Testing": { + "Mocking": "/testing/mocking", + "Integration testing": "/testing/testing", + "Apollo Studio Explorer": "https://www.apollographql.com/docs/studio/explorer/", + "GraphQL Playground": "/testing/graphql-playground" + }, + "Performance": { + "Caching": "/performance/caching", + "Automatic persisted queries": "/performance/apq" + }, + "Security": { + "Auth": "/security/authentication", + "Terminating SSL": "/security/terminating-ssl" + }, + "Integrations": { + "Node.js middleware": "/integrations/middleware", + "Plugins": "/integrations/plugins" + }, + "Deployment": { + "Heroku": "/deployment/heroku", + "Lambda": "/deployment/lambda", + "Netlify": "/deployment/netlify", + "Azure Functions": "/deployment/azure-functions", + "Google Cloud Functions": "/deployment/gcp-functions" + }, + "Monitoring": { + "Metrics and logging": "/monitoring/metrics", + "Health checks": "/monitoring/health-checks" + }, + "API Reference": { + "apollo-server": "/api/apollo-server", + "Usage reporting plugin": "/api/plugin/usage-reporting", + "Schema reporting plugin": "/api/plugin/schema-reporting", + "Inline trace plugin": "/api/plugin/inline-trace", + "graphql-tools": "/api/graphql-tools", + "@apollo/federation": "https://www.apollographql.com/docs/federation/api/apollo-federation/", + "@apollo/gateway": "https://www.apollographql.com/docs/federation/api/apollo-gateway/" + }, + "Appendices": { + "Proxy configuration": "/proxy-configuration", + "Installing graphql-tools": "/installing-graphql-tools", + "File uploads in Node.js < v8.5.0": "/migration-file-uploads", + "Migrating from the \"engine\" option": "/migration-engine-plugins" + } + } +} diff --git a/docs/source/data/data-sources.mdx b/docs/source/data/data-sources.mdx index ffc859bc3f9..0363fe9e07d 100644 --- a/docs/source/data/data-sources.mdx +++ b/docs/source/data/data-sources.mdx @@ -3,10 +3,6 @@ title: Data sources description: Manage connections to databases and REST APIs --- -import { - ExpansionPanel, -} from 'gatsby-theme-apollo-docs/src/components/expansion-panel'; - **Data sources** are classes that Apollo Server can use to encapsulate fetching data from a particular source, such as a database or a REST API. These classes help handle caching, deduplication, and errors while resolving operations. Your server can use any number of different data sources. You don't _have_ to use data sources to fetch data, but they're strongly recommended. @@ -54,7 +50,7 @@ If none of these implementations applies to your use case, you can create your o You provide your `DataSource` subclasses to the `ApolloServer` constructor, like so: -```js{4-9}:title=index.js +```js {4-9} title="index.js" const server = new ApolloServer({ typeDefs, resolvers, @@ -73,7 +69,7 @@ const server = new ApolloServer({ Your resolvers can now access your data sources from the shared `context` object and use them to fetch data: -```js:title=resolvers.js +```js title="resolvers.js" const resolvers = { Query: { movie: async (_, { id }, { dataSources }) => { @@ -123,7 +119,7 @@ For the options you can pass to the underlying Memcached client, [see the docume #### Redis -```js:title=Redis +```js title="Redis" const { BaseRedisCache } = require('apollo-server-cache-redis'); const Redis = require('ioredis'); @@ -166,7 +162,7 @@ You then extend the `RESTDataSource` class and implement whatever data-fetching Here's an example `RESTDataSource` subclass that defines two data-fetching methods, `getMovie` and `getMostViewedMovies`: -```js:title=movies-api.js +```js title="movies-api.js" const { RESTDataSource } = require('apollo-datasource-rest'); class MoviesAPI extends RESTDataSource { diff --git a/docs/source/data/errors.mdx b/docs/source/data/errors.mdx index 6a44f55b50e..58067aab00f 100644 --- a/docs/source/data/errors.mdx +++ b/docs/source/data/errors.mdx @@ -3,8 +3,6 @@ title: Error handling description: Making errors actionable on the client and server --- -import {ExpansionPanel} from 'gatsby-theme-apollo-docs'; - Whenever Apollo Server encounters errors while processing a GraphQL operation, its response to the client includes an `errors` array that contains each error that occurred. Each error in the array has an `extensions` field that provides additional useful information, including an error `code` and (while in development mode) an `exception.stacktrace`. Here's an example error response caused by misspelling the `__typename` field in a query: @@ -176,7 +174,7 @@ For example, this resolver throws a [`UserInputError`](#bad_user_input) if the i -```js{20-25} +```js {20-25} const { ApolloServer, gql, @@ -218,7 +216,7 @@ This example builds on the one above by adding the name of the GraphQL argument -```js{22-24} +```js {22-24} const { ApolloServer, gql, @@ -256,7 +254,7 @@ This results in a response like the following: -```json{15} +```json {15} { "errors": [ { @@ -339,7 +337,7 @@ The `ApolloServer` constructor accepts a `formatError` function that is run on e This example returns a more generic error whenever the original error's message begins with `Database Error: `: -```js{4-12} +```js {4-12} const server = new ApolloServer({ typeDefs, resolvers, @@ -391,7 +389,7 @@ Your `rewriteError` function is called for each error (a `GraphQLError` or an `A Let's say our server is `throw`ing an `AuthenticationError` whenever an incorrect password is provided. We can avoid reporting these errors to Apollo Studio by defining `rewriteError`, like so: -```js{7-17} +```js {7-17} const { ApolloServer, AuthenticationError } = require("apollo-server"); const { ApolloServerPluginUsageReporting } = require("apollo-server-core"); const server = new ApolloServer({ @@ -421,7 +419,7 @@ When generating an error (e.g., `new ApolloError("Failure!")`), the error's `mes We can check these properties when determining whether an error should be reported to Apollo Studio using the `rewriteError` function as follows: -```js{7-17} +```js {7-17} const { ApolloServer } = require("apollo-server"); const { ApolloServerPluginUsageReporting } = require("apollo-server-core"); const server = new ApolloServer({ @@ -458,7 +456,7 @@ throw new ApolloError("The x-api-key:12345 doesn't have sufficient privileges.") The `rewriteError` function can ensure that such information is not sent to Apollo Studio and potentially revealed outside its intended scope: -```js{7-13} +```js {7-13} const { ApolloServer } = require("apollo-server"); const { ApolloServerPluginUsageReporting } = require("apollo-server-core"); const server = new ApolloServer({ diff --git a/docs/source/data/resolvers.mdx b/docs/source/data/resolvers.mdx index 2004074bce0..0a7a6e0b5e2 100644 --- a/docs/source/data/resolvers.mdx +++ b/docs/source/data/resolvers.mdx @@ -3,10 +3,6 @@ title: Resolvers description: How Apollo Server processes GraphQL operations --- -import { - ExpansionPanel, -} from 'gatsby-theme-apollo-docs/src/components/expansion-panel'; - Apollo Server needs to know how to populate data for every field in your schema so that it can respond to requests for that data. To accomplish this, it uses resolvers. **A resolver is a function that's responsible for populating the data for a single field in your schema.** It can populate that data in any way you define, such as by fetching data from a back-end database or a third-party API. @@ -324,7 +320,7 @@ server.listen().then(({ url }) => { If we now update our query to also ask for each book's `title`: -```graphql{4} +```graphql {4} query GetBooksByLibrary { libraries { books { @@ -357,14 +353,14 @@ Resolver functions are passed four arguments: `parent`, `args`, `context`, and ` | Argument | Description | |---|---| -| `parent` |

The return value of the resolver for this field's parent (i.e., the previous resolver in the [resolver chain](#resolver-chains)).

For resolvers of top-level fields with no parent (such as fields of `Query`), this value is obtained from the `rootValue` function passed to [Apollo Server's constructor](/api/apollo-server/#constructor).

| +| `parent` |

The return value of the resolver for this field's parent (i.e., the previous resolver in the [resolver chain](#resolver-chains)).

For resolvers of top-level fields with no parent (such as fields of `Query`), this value is obtained from the `rootValue` function passed to [Apollo Server's constructor](../api/apollo-server/#constructor).

| | `args` |

An object that contains all GraphQL arguments provided for this field.

For example, when executing `query{ user(id: "4") }`, the `args` object passed to the `user` resolver is `{ "id": "4" }`.

| | `context` |

An object shared across all resolvers that are executing for a particular operation. Use this to share per-operation state, including authentication information, dataloader instances, and anything else to track across resolvers.

See [The `context` argument](#the-context-argument) for more information.

| | `info` |

Contains information about the operation's execution state, including the field name, the path to the field from the root, and more.

Its core fields are listed in the [GraphQL.js source code](https://github.com/graphql/graphql-js/blob/main/src/type/definition.ts#L965-L976), and it is extended with additional functionality by other modules, like [`apollo-cache-control`](https://github.com/apollographql/apollo-server/tree/570f548b887/packages/apollo-cache-control).

| ### The `context` argument -The `context` argument is useful for passing things that any resolver might need, like [authentication scope](https://blog.apollographql.com/authorization-in-graphql-452b1c402a9), database connections, and custom fetch functions. If you're using [dataloaders to batch requests](/data/data-sources/#using-with-dataloader) across resolvers, you can attach them to the `context` as well. +The `context` argument is useful for passing things that any resolver might need, like [authentication scope](https://blog.apollographql.com/authorization-in-graphql-452b1c402a9), database connections, and custom fetch functions. If you're using [dataloaders to batch requests](./data-sources/#using-with-dataloader) across resolvers, you can attach them to the `context` as well. **Resolvers should never destructively modify the `context` argument.** This ensures consistency across all resolvers and prevents unexpected errors. @@ -388,7 +384,7 @@ const server = new ApolloServer({ } ``` -> The fields of the object passed to your `context` function differ if you're using middleware besides Express. [See the API reference for details.](/api/apollo-server/#middleware-specific-context-fields) +> The fields of the object passed to your `context` function differ if you're using middleware besides Express. [See the API reference for details.](../api/apollo-server/#middleware-specific-context-fields) Context initialization can be asynchronous, allowing database connections and other operations to complete: diff --git a/docs/source/data/subscriptions.mdx b/docs/source/data/subscriptions.mdx index d937cde0b69..ece8f0bcf61 100644 --- a/docs/source/data/subscriptions.mdx +++ b/docs/source/data/subscriptions.mdx @@ -3,8 +3,6 @@ title: Subscriptions description: Persistent GraphQL read operations --- -import {ExpansionPanel} from 'gatsby-theme-apollo-docs'; - > **Subscriptions are not currently supported in [Apollo Federation](https://www.apollographql.com/docs/federation/).** **Subscriptions** are long-lasting GraphQL read operations that can update their result whenever a particular server-side event occurs. Most commonly, updated results are _pushed_ from the server to subscribing clients. For example, a chat application's server might use a subscription to push newly received messages to all clients in a particular chat room. @@ -59,7 +57,7 @@ const server = new ApolloServer({ Resolvers for `Subscription` fields differ from resolvers for fields of other types. Specifically, `Subscription` field resolvers are _objects_ that define a `subscribe` function: -```js:title=index.js +```js title="index.js" const resolvers = { Subscription: { postCreated: { @@ -118,7 +116,7 @@ type Mutation { A basic resolver for `createPost` might look like this: -```js{3-6} +```js {3-6} const resolvers = { Mutation: { createPost(parent, args, context) { @@ -158,7 +156,7 @@ You pass this method an array containing the names of all event labels that the Every `Subscription` field resolver's `subscribe` function must return an `AsyncIterator` object. This brings us back to the code sample at the top of [Resolving a subscription](#resolving-a-subscription): -```js:title=index.js +```js title="index.js" const resolvers = { Subscription: { postCreated: { @@ -194,7 +192,7 @@ To fix this, we can use the `withFilter` helper function to control updates on a Here's an example resolver for `commentAdded` that uses the `withFilter` function: -```js{5-12} +```js {5-12} const { withFilter } = require('apollo-server'); const resolvers = { diff --git a/docs/source/deployment/azure-functions.md b/docs/source/deployment/azure-functions.md index d46b33e94f8..c12433d6219 100644 --- a/docs/source/deployment/azure-functions.md +++ b/docs/source/deployment/azure-functions.md @@ -1,6 +1,5 @@ --- title: Deploying with Azure Functions -sidebar_title: Azure Functions description: Deploying your GraphQL server to Azure Functions --- This is the Azure Functions integration for the Apollo community GraphQL Server. [Read Docs](https://www.npmjs.com/package/apollo-server-azure-functions) diff --git a/docs/source/deployment/gcp-functions.mdx b/docs/source/deployment/gcp-functions.mdx index ca3a8a4bf29..453d899d9aa 100644 --- a/docs/source/deployment/gcp-functions.mdx +++ b/docs/source/deployment/gcp-functions.mdx @@ -1,17 +1,12 @@ --- title: Deploying with Google Cloud Functions -sidebar_title: Google Cloud Functions --- -import { - ExpansionPanel, -} from 'gatsby-theme-apollo-docs/src/components/expansion-panel'; - This tutorial helps you deploy Apollo Server to Google Cloud Functions. It uses the following example function handler: -```javascript:title=index.js +```javascript title="index.js" const { ApolloServer, gql } = require('apollo-server-cloud-functions'); // Construct a schema, using GraphQL schema language @@ -30,7 +25,7 @@ const resolvers = { /* Because `NODE_ENV` is a reserved environment variable in Google Cloud Functions -and it defaults to "production", you need to set both the `playground` and +and it defaults to "production", you need to set both the `playground` and `introspection` options to `true` for GraphQL Playground to work correctly. */ const server = new ApolloServer({ @@ -66,7 +61,7 @@ Paste the example code at the top of this page into the contents of `index.js` i Edit `package.json` so that it lists `apollo-server-cloud-functions` and `graphql` in its dependencies: -```json:title=package.json +```json title="package.json" "dependencies": { "apollo-server-cloud-functions": "^2.24.0", "graphql": "^15.5.0" @@ -184,7 +179,7 @@ exports.handler = server.createHandler(); To enable CORS, you need to modify your HTTP response headers. To do so, use the `cors` option: -```javascript{23-26} +```javascript {23-26} const { ApolloServer, gql } = require('apollo-server-cloud-functions'); // Construct a schema, using GraphQL schema language diff --git a/docs/source/deployment/heroku.md b/docs/source/deployment/heroku.md index 8ed288f21e9..4bfe6a005b3 100644 --- a/docs/source/deployment/heroku.md +++ b/docs/source/deployment/heroku.md @@ -1,6 +1,5 @@ --- title: Deploying with Heroku -sidebar_title: Heroku description: Deploying your GraphQL server to Heroku --- diff --git a/docs/source/deployment/index.md b/docs/source/deployment/index.md index 144061a7a78..d37f36db132 100644 --- a/docs/source/deployment/index.md +++ b/docs/source/deployment/index.md @@ -1,6 +1,5 @@ --- title: Deployment Basics -sidebar_title: Basics description: Deploying your new Apollo Server to the world --- diff --git a/docs/source/deployment/lambda.md b/docs/source/deployment/lambda.md index 96f73fe376e..338245c50ca 100644 --- a/docs/source/deployment/lambda.md +++ b/docs/source/deployment/lambda.md @@ -1,6 +1,5 @@ --- title: Deploying with AWS Lambda -sidebar_title: Lambda description: How to deploy Apollo Server with AWS Lambda --- diff --git a/docs/source/deployment/netlify.md b/docs/source/deployment/netlify.md index cda5339a559..66992eedba3 100644 --- a/docs/source/deployment/netlify.md +++ b/docs/source/deployment/netlify.md @@ -1,6 +1,5 @@ --- title: Deploying with Netlify Functions -sidebar_title: Netlify description: How to run your API using Netlify Functions on AWS Lambda --- diff --git a/docs/source/getting-started.mdx b/docs/source/getting-started.mdx index c0a72790ef6..3458d142153 100644 --- a/docs/source/getting-started.mdx +++ b/docs/source/getting-started.mdx @@ -1,12 +1,7 @@ --- title: Get started with Apollo Server -sidebar_title: Get started --- -import { - ExpansionPanel, -} from 'gatsby-theme-apollo-docs/src/components/expansion-panel'; - > This tutorial walks you through installing and configuring Apollo Server. > If you're just getting started with GraphQL or the Apollo > platform, we recommend first completing the [full-stack tutorial](https://www.apollographql.com/docs/tutorial/introduction/). @@ -71,7 +66,7 @@ of books by title and author. Open `index.js` in your preferred editor and paste the following into it: -```js:title=index.js +```js title="index.js" const { ApolloServer, gql } = require('apollo-server'); // A schema is a collection of type definitions (hence "typeDefs") @@ -107,7 +102,7 @@ server). For the purposes of this tutorial, we'll just hardcode some example dat Add the following to the bottom of `index.js`: -```js:title=index.js +```js title="index.js" const books = [ { title: 'The Awakening', @@ -135,7 +130,7 @@ straightforward. Add the following to the bottom of `index.js`: -```js:title=index.js +```js title="index.js" // Resolvers define the technique for fetching the types defined in the // schema. This resolver retrieves books from the "books" array above. const resolvers = { @@ -152,7 +147,7 @@ this information to Apollo Server when we initialize it. Add the following to the bottom of `index.js`: -```js:title=index.js +```js title="index.js" // The ApolloServer constructor requires two parameters: your schema // definition and your set of resolvers. const server = new ApolloServer({ typeDefs, resolvers }); @@ -231,6 +226,6 @@ This example application is a great starting point for working with Apollo Server. Check out the following resources to learn more about the basics of schemas, resolvers, and deployment: -* [Schema basics](/schema/schema/) -* [Resolvers](/data/resolvers/) -* [Deploying with Heroku](/deployment/heroku/) +* [Schema basics](./schema/schema/) +* [Resolvers](./data/resolvers/) +* [Deploying with Heroku](./deployment/heroku/) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 90d0667c4b8..1f620056e9a 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,6 +1,5 @@ --- title: Introduction to Apollo Server -sidebar_title: Introduction --- **Apollo Server is an [open-source](https://github.com/apollographql/apollo-server), spec-compliant GraphQL server** that's compatible with any GraphQL client, including [Apollo Client](https://www.apollographql.com/docs/react). It's the best way to build a production-ready, self-documenting GraphQL API that can use data from any source. @@ -22,11 +21,10 @@ sidebar_title: Introduction #### Ready to try it out? -import {Button} from '@apollo/space-kit/Button'; import {Link} from 'gatsby';
-
diff --git a/docs/source/installing-graphql-tools.md b/docs/source/installing-graphql-tools.md index a07824856c5..51add0c092a 100644 --- a/docs/source/installing-graphql-tools.md +++ b/docs/source/installing-graphql-tools.md @@ -8,7 +8,7 @@ Apollo Server includes `graphql-tools` version 4 by default. If you want to use 2. Update your `ApolloServer` constructor to provide the `schema` option _instead of_ `typeDefs`, `resolvers`, and `schemaDirectives`. You instead pass these options to the `makeExecutableSchema` function, which you provide as the value of `schema`: - ```js:title=index.js + ```js title="index.js" const { ApolloServer, gql } = require("apollo-server"); const { makeExecutableSchema } = require("@graphql-tools/schema"); @@ -26,7 +26,7 @@ Apollo Server includes `graphql-tools` version 4 by default. If you want to use 3. Add the following definitions to your schema `typeDefs`: - ```graphql:title=schema.graphql + ```graphql title="schema.graphql" enum CacheControlScope { PUBLIC PRIVATE diff --git a/docs/source/integrations/middleware.md b/docs/source/integrations/middleware.md index a081b5e5fbc..e553533282c 100644 --- a/docs/source/integrations/middleware.md +++ b/docs/source/integrations/middleware.md @@ -1,6 +1,5 @@ --- title: Integrating with Node.js middleware -sidebar_title: Node.js middleware description: Use Apollo Server with Express, Koa, and more --- diff --git a/docs/source/integrations/plugins.md b/docs/source/integrations/plugins.md index 96d8afd2f75..953ccb13b82 100644 --- a/docs/source/integrations/plugins.md +++ b/docs/source/integrations/plugins.md @@ -17,7 +17,7 @@ with each request that's sent to Apollo Server. Plugins are JavaScript objects that implement one or more functions that respond to events. Here's a basic plugin that responds to the `serverWillStart` event: -```js:title=index.js +```js title="index.js" const myPlugin = { serverWillStart() { console.log('Server starting up!'); @@ -30,7 +30,7 @@ const myPlugin = { You can define a plugin in the same file where you initialize Apollo Server, or you can export it as a separate module: -```js:title=myplugin.js +```js title="myplugin.js" module.exports = { serverWillStart() { console.log('Server starting up!'); @@ -41,7 +41,7 @@ module.exports = { To create a plugin that accepts options, create a function that accepts an `options` object and returns a properly structured plugin object, like so: -```js:title=myplugin.js +```js title="myplugin.js" module.exports = (options) => { return { serverWillStart() { @@ -252,7 +252,7 @@ Request lifecycle events are associated with a specific request. You define resp ### `serverWillStart` -The `serverWillStart` event fires when Apollo Server is preparing to start serving GraphQL requests. If you respond to this event with an `async` function (or if the function returns a `Promise`), the server doesn't start until the asynchronous operation completes. If the `Promise` is _rejected_, startup _fails_ (**unless you're using [Express middleware](/integrations/middleware/)**). This helps you make sure all +The `serverWillStart` event fires when Apollo Server is preparing to start serving GraphQL requests. If you respond to this event with an `async` function (or if the function returns a `Promise`), the server doesn't start until the asynchronous operation completes. If the `Promise` is _rejected_, startup _fails_ (**unless you're using [Express middleware](./middleware/)**). This helps you make sure all of your server's dependencies are available before attempting to begin serving requests. #### Example diff --git a/docs/source/migration-two-dot.md b/docs/source/migration-two-dot.md index 447a5219183..0bf556c3c92 100644 --- a/docs/source/migration-two-dot.md +++ b/docs/source/migration-two-dot.md @@ -13,7 +13,7 @@ Apollo Server 2.0 ships with the `gql` tag for **editor syntax highlighting** an The `gql` tag parses the query string into an AST and is now exported from the new `apollo-server` package. -```js{1,3} +```js {1,3} const { ApolloServer, gql } = require('apollo-server'); const typeDefs = gql` @@ -283,7 +283,7 @@ new ApolloServer({ ## Replacing `logFunction` -Apollo Server 2 removes the `logFunction` to reduce the exposure of internal implementation details. The experimental, non-public `graphql-extensions` provides a more structured and flexible way of instrumenting Apollo Server. An explanation of to do more granular logging, can be found in the [metrics section](/monitoring/metrics/). +Apollo Server 2 removes the `logFunction` to reduce the exposure of internal implementation details. The experimental, non-public `graphql-extensions` provides a more structured and flexible way of instrumenting Apollo Server. An explanation of to do more granular logging, can be found in the [metrics section](./monitoring/metrics/). ## Replacing GraphiQL diff --git a/docs/source/monitoring/health-checks.md b/docs/source/monitoring/health-checks.md index 0704e44b05d..76407a0ad86 100644 --- a/docs/source/monitoring/health-checks.md +++ b/docs/source/monitoring/health-checks.md @@ -1,6 +1,6 @@ --- title: Health checks -description: Determining the health status of the Apollo Server +description: Determining the health status of the Apollo Server --- Health checks are often used by load balancers to determine if a server is available and ready to start serving traffic. By default, Apollo Server provides a health check endpoint at `/.well-known/apollo/server-health` which returns a 200 status code if the server has started. @@ -9,7 +9,7 @@ This basic health check may not be comprehensive enough for some applications an > **Note:** Alternatively, the `onHealthCheck` can be defined as an `async` function which `throw`s if it encounters an error and returns when conditions are considered normal. -```js{10-19} +```js {10-19} const { ApolloServer, gql } = require('apollo-server'); // Undefined for brevity. diff --git a/docs/source/monitoring/metrics.md b/docs/source/monitoring/metrics.md index dcbcee1e293..d6e91408ade 100644 --- a/docs/source/monitoring/metrics.md +++ b/docs/source/monitoring/metrics.md @@ -48,7 +48,7 @@ version in the [`ApolloClient` constructor](https://www.apollographql.com/docs/r For more advanced cases, or to use headers other than the default headers, pass a `generateClientInfo` function into the [usage reporting plugin](../api/plugin/usage-reporting/): -```js{9-24} +```js {9-24} const { ApolloServer } = require("apollo-server"); const { ApolloServerPluginUsageReporting } = require("apollo-server-core"); diff --git a/docs/source/performance/apq.md b/docs/source/performance/apq.md index 5d10c6f67b1..e0e7d22dccd 100644 --- a/docs/source/performance/apq.md +++ b/docs/source/performance/apq.md @@ -33,7 +33,7 @@ Apollo Server supports APQ without any additional configuration. However, some _ To set up APQ in Apollo Client, first import the `createPersistedQueryLink` function in the same file where you initialize `ApolloClient`: -```js:title=index.js +```js title="index.js" import { createPersistedQueryLink } from "@apollo/client/link/persisted-queries"; ``` @@ -109,7 +109,7 @@ Apollo Server works well with a Content Distribution Network (CDN) to cache full ### Step 1: Add cache hints to the GraphQL schema -Add cache hints as [directives](/schema/directives/) to GraphQL schema so that Apollo Server knows which fields and types are cacheable and for how long. For example, this schema indicates that all fields that return an `Author` should be cached for 60 seconds, and that the `posts` field should itself be cached for 180 seconds: +Add cache hints as [directives](../schema/directives/) to GraphQL schema so that Apollo Server knows which fields and types are cacheable and for how long. For example, this schema indicates that all fields that return an `Author` should be cached for 60 seconds, and that the `posts` field should itself be cached for 180 seconds: ```graphql type Author @cacheControl(maxAge: 60) { diff --git a/docs/source/performance/caching.md b/docs/source/performance/caching.md index e8a22836607..db1c22fe27d 100644 --- a/docs/source/performance/caching.md +++ b/docs/source/performance/caching.md @@ -1,12 +1,11 @@ --- title: Server-side caching -sidebar_title: Caching description: Configure caching behavior on a per-field basis --- Apollo Server enables you to define cache control settings (`maxAge` and `scope`) for each field in your schema: -```graphql{5,7} +```graphql {5,7} type Post { id: ID! title: String @@ -52,7 +51,7 @@ Use `@cacheControl` for fields that should always be cached with the same settin This example defines cache control settings for two fields of the `Post` type: `votes` and `readByCurrentUser`: -```graphql{5,7}:title=schema.graphql +```graphql {5,7} title="schema.graphql" type Post { id: ID! title: String @@ -72,7 +71,7 @@ In this example: This example defines cache control settings for _all_ schema fields that return a `Post` object: -```graphql:title=schema.graphql +```graphql title="schema.graphql" type Post @cacheControl(maxAge: 240) { id: Int! title: String @@ -85,7 +84,7 @@ type Post @cacheControl(maxAge: 240) { If another object type in this schema includes a field of type `Post` (or a list of `Post`s), that field's value is cached for a maximum of 240 seconds: -```graphql:title=schema.graphql +```graphql title="schema.graphql" type Comment { post: Post! # Cached for up to 240 seconds body: String! @@ -94,7 +93,7 @@ type Comment { **Note that [field-level settings](#field-level-definitions) override type-level settings.** In the following case, `Comment.post` is cached for a maximum of 120 seconds, _not_ 240 seconds: -```graphql:title=schema.graphql +```graphql title="schema.graphql" type Comment { post: Post! @cacheControl(maxAge: 120) body: String! diff --git a/docs/source/proxy-configuration.md b/docs/source/proxy-configuration.md index 5fdae327863..e4b20d2cded 100644 --- a/docs/source/proxy-configuration.md +++ b/docs/source/proxy-configuration.md @@ -30,7 +30,7 @@ npm install global-agent After the `global-agent` dependency has been installed, invoke its `bootstrap` method **before** Apollo Server is initialized: -```js{2-5}) +```js {2-5} const { ApolloServer, gql } = require('apollo-server'); const { bootstrap: bootstrapGlobalAgent } = require('global-agent'); diff --git a/docs/source/schema/creating-directives.mdx b/docs/source/schema/creating-directives.mdx index 12bd0bb7ad5..a6fd2adfa9e 100644 --- a/docs/source/schema/creating-directives.mdx +++ b/docs/source/schema/creating-directives.mdx @@ -3,13 +3,11 @@ title: Creating schema directives description: Apply custom logic to GraphQL types, fields, and arguments --- -import {ExpansionPanel} from 'gatsby-theme-apollo-docs'; - > Before you create a custom schema directive, [learn the basics about directives](./directives). Your schema can define custom directives that can then decorate _other_ parts of your schema: -```graphql:title=schema.graphql +```graphql title="schema.graphql" # Definition directive @uppercase on FIELD_DEFINITION @@ -25,7 +23,7 @@ When Apollo Server loads your schema on startup, it can execute custom logic whe A directive definition looks like this: -```graphql:title=schema.graphql +```graphql title="schema.graphql" directive @deprecated( reason: String = "No longer supported" ) on FIELD_DEFINITION | ENUM_VALUE @@ -221,7 +219,7 @@ In your subclass, you override the **visitor method** for _each location_ your d Here's a possible implementation of the default `@deprecated` directive: -```js:title=DeprecatedDirective.js +```js title="DeprecatedDirective.js" const { SchemaDirectiveVisitor } = require("apollo-server"); // Subclass of SchemaDirectiveVisitor @@ -248,7 +246,7 @@ This subclass adds two fields to the executable schema's representation of a dep To add this logic to Apollo Server, you pass the `DeprecatedDirective` class to the `ApolloServer` constructor via the `schemaDirectives` object: -```js:title=index.js +```js title="index.js" const { ApolloServer, gql } = require("apollo-server"); const { DeprecatedDirective } = require("./DeprecatedDirective"); @@ -299,7 +297,7 @@ This example defines an `@uppercase` directive for this purpose: -```js:title=index.js +```js title="index.js" const { ApolloServer, gql, SchemaDirectiveVisitor } = require("apollo-server"); const { defaultFieldResolver } = require("graphql"); diff --git a/docs/source/schema/custom-scalars.md b/docs/source/schema/custom-scalars.md index 572955ba4e2..ed2990520a5 100644 --- a/docs/source/schema/custom-scalars.md +++ b/docs/source/schema/custom-scalars.md @@ -84,7 +84,7 @@ In [the example above](#example-the-date-scalar), `parseLiteral` converts the AS After you define your `GraphQLScalarType` instance, you include it in the same [resolver map](../data/resolvers/#defining-a-resolver) that contains resolvers for your schema's other types and fields: -```js{21-24} +```js {21-24} const { ApolloServer, gql } = require('apollo-server'); const { GraphQLScalarType, Kind } = require('graphql'); @@ -120,7 +120,7 @@ const server = new ApolloServer({ In this example, we create a custom scalar called `Odd` that can only contain odd integers: -```js{19-30} +```js {19-30} const { ApolloServer, gql } = require('apollo-server'); const { GraphQLScalarType, Kind } = require('graphql'); diff --git a/docs/source/schema/directives.md b/docs/source/schema/directives.md index 8444fdd4307..643fbf7da6b 100644 --- a/docs/source/schema/directives.md +++ b/docs/source/schema/directives.md @@ -1,6 +1,5 @@ --- title: Directives -sidebar_title: Directives description: Configure GraphQL types, fields, and arguments --- @@ -8,7 +7,7 @@ A **directive** decorates part of a GraphQL schema or operation with additional Directives are preceded by the `@` character, like so: -```graphql{2}:title=schema.graphql +```graphql {2} title="schema.graphql" type ExampleType { oldField: String @deprecated(reason: "Use `newField`.") newField: String @@ -34,7 +33,7 @@ directive @deprecated( This indicates that `@deprecated` can decorate either a schema `FIELD_DEFINITION` (as shown at the top of the article) or a schema `ENUM_VALUE` definition (as shown here): -```graphql:title=schema.graphql +```graphql title="schema.graphql" enum MyEnum { OLD_VALUE @deprecated(reason: "Use `NEW_VALUE`.") NEW_VALUE @@ -78,7 +77,7 @@ To use a custom directive: The following example defines an `UpperCaseDirective` subclass for use with the `@upper` custom directive. Because it's decorated with `@upper`, the `Query.hello` field returns `HELLO WORLD!` instead of `Hello world!`. -```js{20,40-42} +```js {20,40-42} const { ApolloServer, gql, SchemaDirectiveVisitor } = require('apollo-server'); const { defaultFieldResolver } = require('graphql'); diff --git a/docs/source/schema/schema.md b/docs/source/schema/schema.md index 7d58403f840..abf4978fbb2 100644 --- a/docs/source/schema/schema.md +++ b/docs/source/schema/schema.md @@ -55,7 +55,7 @@ GraphQL's default scalar types are: * `Boolean`: `true` or `false` * `ID` (serialized as a `String`): A unique identifier that's often used to refetch an object or as the key for a cache. Although it's serialized as a `String`, an `ID` is not intended to be human‐readable. -These primitive types cover the majority of use cases. For more specific use cases, you can create [custom scalar types](/schema/custom-scalars/). +These primitive types cover the majority of use cases. For more specific use cases, you can create [custom scalar types](./custom-scalars/). ### Object types diff --git a/docs/source/schema/unions-interfaces.md b/docs/source/schema/unions-interfaces.md index 8ed0fc51bbd..43bce0d572c 100644 --- a/docs/source/schema/unions-interfaces.md +++ b/docs/source/schema/unions-interfaces.md @@ -77,7 +77,7 @@ The `__resolveType` function uses a returned object's fields to determine its ty Here's an example `__resolveType` function for the `Result` union defined above: -```js{3-11} +```js {3-11} const resolvers = { Result: { __resolveType(obj, context, info){ @@ -209,7 +209,7 @@ For more information, see [Using fragments with unions and interfaces](https://w Here's an example `__resolveType` function for the `Book` interface defined above: -```js{3-11} +```js {3-11} const resolvers = { Book: { __resolveType(book, context, info){ diff --git a/docs/source/security/authentication.md b/docs/source/security/authentication.md index 6c8d5d8dc2c..dd1f2128fd8 100644 --- a/docs/source/security/authentication.md +++ b/docs/source/security/authentication.md @@ -1,6 +1,5 @@ --- title: Authentication and authorization -sidebar_title: Auth description: Control access to your GraphQL API --- diff --git a/docs/source/security/terminating-ssl.md b/docs/source/security/terminating-ssl.md index c07f9d4cf67..c2ee0a099d9 100644 --- a/docs/source/security/terminating-ssl.md +++ b/docs/source/security/terminating-ssl.md @@ -5,7 +5,7 @@ title: Terminating SSL Most production environments use a load balancer or HTTP proxy (such as nginx) to perform SSL termination on behalf of web applications in that environment. If you're using Apollo Server in an application that must perform its _own_ SSL termination, you can use the `https` module with the `apollo-server-express` [middleware -library](/integrations/middleware/). +library](../integrations/middleware/). Here's an example that uses HTTPS in production and HTTP in development: diff --git a/docs/source/testing/graphql-playground.mdx b/docs/source/testing/graphql-playground.mdx index 89d5fed8875..078008bc253 100644 --- a/docs/source/testing/graphql-playground.mdx +++ b/docs/source/testing/graphql-playground.mdx @@ -3,12 +3,7 @@ title: GraphQL Playground description: Visually explore Apollo Server --- -import { - ExpansionPanel, -} from 'gatsby-theme-apollo-docs/src/components/expansion-panel'; -import { Button } from '@apollo/space-kit/Button'; import { Link } from 'gatsby'; -import { colors } from 'gatsby-theme-apollo-core'; @@ -16,9 +11,11 @@ import { colors } from 'gatsby-theme-apollo-core';

@@ -60,7 +57,7 @@ playground: { To enable GraphQL Playground in production, introspection and the playground can be enabled explicitly in the following manner. -```js{7-8} +```js {7-8} const { ApolloServer } = require('apollo-server'); const { typeDefs, resolvers } = require('./schema'); diff --git a/docs/source/testing/mocking.md b/docs/source/testing/mocking.md index ef5a814a454..9b3c83d33fe 100644 --- a/docs/source/testing/mocking.md +++ b/docs/source/testing/mocking.md @@ -40,7 +40,7 @@ For more sophisticated testing, mocks can be customized to a particular data mod In addition to a boolean, `mocks` can be an object that describes custom mocking logic, which is structured similarly to `resolvers` with a few extra features aimed at mocking. Namely `mocks` accepts functions for specific types in the schema that are called when that type is expected. By default, the functions in `mocks` will overwrite the resolvers in `resolvers`. In this example `hello` and `resolved` will both return `'Hello'`. -```js{16-20} +```js {16-20} const { ApolloServer, gql } = require('apollo-server'); const typeDefs = gql` diff --git a/docs/source/why-apollo-server.md b/docs/source/why-apollo-server.md index 85a1212fcd5..0c4235df9e2 100644 --- a/docs/source/why-apollo-server.md +++ b/docs/source/why-apollo-server.md @@ -6,7 +6,7 @@ Building APIs shouldn't have to be so tricky. If you are concerned about perform ## Schema first design -We think GraphQL's greatest asset is the schema. Think of it like the Rosetta stone of the data your app needs. Schemas represent the touch point of your frontends with the data that powers them. We recommend using the [schema definition language](/schema/schema/#the-schema-definition-language), also called the SDL, to easily write out the data and relationships that your app needs to be successful. Unlike REST APIs, GraphQL schemas shouldn't be a one to one mapping of your database, but rather a representation of how your app works with the data it needs. Let's see what this looks like in practice with Apollo Server: +We think GraphQL's greatest asset is the schema. Think of it like the Rosetta stone of the data your app needs. Schemas represent the touch point of your frontends with the data that powers them. We recommend using the [schema definition language](./schema/schema/#the-schema-definition-language), also called the SDL, to easily write out the data and relationships that your app needs to be successful. Unlike REST APIs, GraphQL schemas shouldn't be a one to one mapping of your database, but rather a representation of how your app works with the data it needs. Let's see what this looks like in practice with Apollo Server: ```js const { ApolloServer, gql } = require('apollo-server'); @@ -40,7 +40,7 @@ server.listen().then(({ url }) => { }); ``` -In the example above, we are describing the shapes of our data, how they relate to each other, and how to fetch what our client needs from our data source. Apollo Server uses simple functions called [resolvers](/data/resolvers/) to bring to life the schema described in SDL type definitions. When a request comes in to `/graphql`, Apollo Server will translate that request into what it takes to execute the query, will run the resolvers for you to load your data, and return the result in JSON so your app can render it out easily! +In the example above, we are describing the shapes of our data, how they relate to each other, and how to fetch what our client needs from our data source. Apollo Server uses simple functions called [resolvers](./data/resolvers/) to bring to life the schema described in SDL type definitions. When a request comes in to `/graphql`, Apollo Server will translate that request into what it takes to execute the query, will run the resolvers for you to load your data, and return the result in JSON so your app can render it out easily! Apollo Server takes care of every step of translating the query your client asks for into the data it needs. It is designed to give you maximum control over how you load the data while taking care of everything else for you! You don't need to worry about parsing the request, validating the query, delivering the response, or even profiling your app. Instead, all you have to do is describe the shape of your data and how to find it; Apollo Server does the rest! 💪