Update persisted queries docs (#3160)

Co-authored-by: Zach FettersMoore <[email protected]> Co-authored-by: Alex Deem <[email protected]> Co-authored-by: Jeff Auriemma <[email protected]> Co-authored-by: Anthony Miller <[email protected]> Co-authored-by: Martin Bonnin <[email protected]>
apollographql · Aug 10, 2023 · 8c7f1cc · 8c7f1cc
1 parent d9e83f2
commit 8c7f1cc
Show file tree

Hide file tree

Showing 4 changed files with 131 additions and 53 deletions.
diff --git a/docs/source/_redirects b/docs/source/_redirects
@@ -2,3 +2,4 @@
 /v1 /docs/ios/
 /tutorial /docs/ios/tutorial/tutorial-introduction
 /tutorial/tutorial-create-project /docs/ios/tutorial/tutorial-add-sdk
+/fetching/apqs /docs/ios/fetching/persisted-queries
diff --git a/docs/source/config.json b/docs/source/config.json
@@ -78,7 +78,7 @@
         "Error Handling":  "/fetching/error-handling",
         "Type Conditions": "/fetching/type-conditions",
         "Custom Scalars": "/custom-scalars",
-        "Automatic Persisted Queries": "/fetching/apqs"
+        "Persisted Queries": "/fetching/persisted-queries"
       },
       true
     ],

diff --git a/docs/source/fetching/apqs.mdx b/docs/source/fetching/apqs.mdx
diff --git a/docs/source/fetching/persisted-queries.mdx b/docs/source/fetching/persisted-queries.mdx
@@ -0,0 +1,129 @@
+---
+title: Persisted Queries
+description: Secure your graph while minimizing request latency
+---
+
+<ClientPQIntro />
+
+## Differences between persisted queries and APQ
+
+<ClientPQDifferences />
+
+## Implementation steps
+
+Both persisted queries and APQs require you to configure code generation and how your client makes requests. If you intend to use persisted queries for safelisting, you also need to generate an operations manifest.
+
+We recommend you follow this order while implementing:
+
+| Implementation Step | Required for PQs? | Required for APQs? |
+| -----| ------------------ | ----------------- |
+| 1. Configure generated operation models| ✅ | ✅ |
+| 2. Generate the operation manifest |✅ | -- |
+| 3. Publish the operation manifest |✅ | -- |
+| 4. Enable persisted queries on the client when it makes requests | ✅ | ✅ |
+
+The rest of this article details these steps.
+
+Persisted queries also require you to create and link a PQL, and to configure your router to receive persisted query requests. This document only describes the steps that need to be taken by the client to create a manifest of the client's operations and send persisted query requests. For more information on the other configuration aspects of persisted queries, see the [GraphOS persisted queries documentation](/graphos/operations/persisted-queries).
+
+### 0. Requirements
+
+You can use APQ with the following versions of Apollo iOS, Apollo Server, and Apollo Router:
+- Apollo iOS (v1.0.0+)
+- [Apollo Server](/apollo-server/) (v1.0.0+)
+- [Apollo Router](/router) (v0.1.0+)
+
+> **Note:** You can use _either_ Apollo Server _or_ Apollo Router for APQs. They don't need to be used together.
+
+Persisted queries is currently in [preview](/resources/product-launch-stages#preview) and has the following requirements:
+- Apollo iOS (v1.4.0+)
+- [Apollo Router](/router) (v1.25.0+)
+- [GraphOS Enterprise plan](/graphos/enterprise/)
+
+### 1. Configure generated operation models
+
+Both persisted queries and APQs require your code generation to include operation IDs. You can configure this in your code generation configuration's [`options`](output-options).
+Specifically, set the `operationDocumentFormat` array to `definition`, `operationId`, or both `definition` and `operationId`.
+- To use APQs, you must include both the `definition` and `operationId`.
+- For persisted queries, you only need the `operationId`.
+
+```json title="apollo-codegen-config.json"
+"options": {
+    "operationDocumentFormat" : [
+        "definition",
+        "operationId"
+    ]
+}
+```
+
+### 2. Generate operation manifest
+
+> This step is only required for implementing safelisting with persisted queries. It is _not_ required for APQs.
+
+An operation manifest acts as a safelist of trusted operations the [Apollo Router](/router/) can check incoming requests against. You can generate operation manifests by adding the [`operationManifest`](./../code-generation/codegen-configuration#operation-manifest-configuration) option to your `ApolloCodegenConfiguration` JSON file like so:
+
+```json title="apollo-codegen-config.json"
+"operationManifest" : {
+  "generateManifestOnCodeGeneration" : false,
+  "path" : "/operation/identifiers/path",
+  "version" : "persistedQueries"
+}
+```
+
+Once these options are configured you can run the [`generate-operation-manifest`](./../code-generation/codegen-cli#generate-operation-manifest) in order to generate your operation manifest. If you have the `generateManifestOnCodeGeneration` flag set to `true` your operation manifest will also generate everytime you run the [`generate`](./../code-generation/codegen-cli#generate) command.
+
+The resulting operation manifest for `persistedQueries` looks like this: 
+
+```json title="operationIdentifiers.json"
+{
+  "format": "apollo-persisted-query-manifest",
+  "version": 1,
+  "operations": [
+    {
+      "id": "e0321f6b438bb42c022f633d38c19549dea9a2d55c908f64c5c6cb8403442fef",
+      "body": "query GetItem { thing { __typename } }",
+      "name": "GetItem",
+      "type": "query"
+    }
+  ]
+}
+```
+
+To automatically update the manifest for each new app release, you can include the [`generate`](./../code-generation/codegen-cli#generate) or [`generate-operation-manifest`](./../code-generation/codegen-cli#generate-operation-manifest) command in your CI/CD pipeline.
+
+### 3. Publish operation manifest
+
+> This step is only required for implementing safelisting with persisted queries. It is _not_ required for APQs.
+
+<PublishPQMs />
+
+### 4. Enable persisted queries on `ApolloClient`
+
+Once you've configured your code generation to include operation IDs, you can update your client to query by operation ID rather than the full operation string. This configuration is the same whether you're using APQ or persisted queries:
+
+- Initialize a custom `NetworkTransport` using `RequestChainNetworkTransport` with `autoPersistQueries` parameter set to `true` and an `interceptorProvider` that includes the `AutomaticPersistedQueryInterceptor` (such as `DefaultInterceptorProvider`).
+- Initialize your `ApolloClient` with the custom `NetworkTransport` that supports persisted queries.
+
+```swift
+let store = ApolloStore(cache: InMemoryNormalizedCache())
+let interceptorProvider = DefaultInterceptorProvider(store: store)
+let networkTransport = RequestChainNetworkTransport(
+    interceptorProvider: interceptorProvider,
+    endpointURL: URL(string: "http://localhost:4000/graphql")!,
+    autoPersistQueries: true
+)
+
+let client = ApolloClient(networkTransport: networkTransport, store: store)
+```
+
+For more information on configuring your `ApolloClient`, `NetworkTransport`, `InterceptorProvider`, and the request chain, see the [request pipeline](./../networking/request-pipeline) documentation.
+
+#### Sending APQ retries as `GET` requests
+
+> **Note:** Apollo iOS only retries failed ID-based operations for APQs, not persisted queries.
+
+By default, the Apollo clients sends operation retries as `POST` requests.  In some cases, you may prefer or need to retry an operation using a `GET` request: for example, you may make requests to a CDN that has better performance with `GET`s.
+
+To use `GET` for APQ retry requests, set the `useGETForPersistedQueryRetry` on your `RequestChainNetworkTransport` to `true`.
+
+In most cases, keeping the default option (`false`) suffices.