web: deprecate requestGraphQL and update http-client README (#47597)

Make it explicit that the recommended way of fetching data from web
applications is Apollo Client. Based on [the discussion in this PR
review](https://github.com/sourcegraph/sourcegraph/pull/46883#discussion_r1103974825).

client/browser/src/shared/backend/requestGraphQl.ts

@@ -82,6 +82,9 @@ export function createGraphQLHelpers(sourcegraphURL: string, isExtension: boolea
         return createMainThreadExtensionGraphQLHelpers()
     }
 
+    /**
+     * @deprecated Prefer using Apollo-Client instead if possible. The migration is in progress.
+     */
     const requestGraphQL = <T, V = object>({
         request,
         variables,

client/http-client/README.md

@@ -1,3 +1,5 @@
 # Http Client
 
 Generic logic for sending and handling HTTP requests from our client applications.
+
+Use the `getGraphQLClient` client utility to create an app-specific instance of the Apollo Client, which is the recommended way to interact with Sourcegraph API from web applications.

client/http-client/src/graphql/graphql.ts

@@ -71,6 +71,8 @@ export const buildGraphQLUrl = ({ request, baseUrl }: BuildGraphQLUrlOptions): s
  * This function should not be called directly as it does not
  * add the necessary headers to authorize the GraphQL API call.
  * Use `requestGraphQL()` in `client/web/src/backend/graphql.ts` instead.
+ *
+ * @deprecated Prefer using Apollo-Client instead if possible. The migration is in progress.
  */
 export function requestGraphQLCommon<T, V = object>({
     request,

client/jetbrains/webview/src/search/App.tsx

@@ -83,6 +83,9 @@ export const App: React.FunctionComponent<React.PropsWithChildren<Props>> = ({
 }) => {
     const authState = authenticatedUser !== null ? 'success' : 'failure'
 
+    /**
+     * @deprecated Prefer using Apollo-Client instead if possible. The migration is in progress.
+     */
     const requestGraphQL = useCallback<PlatformContext['requestGraphQL']>(
         args =>
             requestGraphQLCommon({

client/web/src/backend/graphql.ts

@@ -34,6 +34,8 @@ const getHeaders = (): { [header: string]: string } => {
  * @returns Observable That emits the result or errors if the HTTP request failed
  * @template TResult The type of the query result (import from our auto-generated types).
  * @template TVariables The type of the query input variables (import from our auto-generated types).
+ *
+ * @deprecated Prefer using Apollo-Client instead if possible. The migration is in progress.
  */
 export const requestGraphQL = <TResult, TVariables = object>(
     request: string,
@@ -54,7 +56,7 @@ type WebGraphQlOperationResults = ReturnType<WebGraphQlOperations[keyof WebGraph
  * @param variables A key/value object with variable values
  * @returns Observable That emits the result or errors if the HTTP request failed
  *
- * @deprecated Prefer using `requestGraphQL()` and passing auto-generated query types as type parameters.
+ * @deprecated Prefer using Apollo-Client instead if possible. The migration is in progress.
  */
 export const queryGraphQL = <TResult extends WebGraphQlOperationResults>(
     request: string,
@@ -73,7 +75,7 @@ export const queryGraphQL = <TResult extends WebGraphQlOperationResults>(
  * @param variables A key/value object with variable values
  * @returns Observable That emits the result or errors if the HTTP request failed
  *
- * @deprecated Prefer using `requestGraphQL()` and passing auto-generated query types as type parameters.
+ * @deprecated Prefer using Apollo-Client instead if possible. The migration is in progress.
  */
 export const mutateGraphQL = <TResult extends WebGraphQlOperationResults>(
     request: string,