From 838f368ccb29f009be40e66d64b82d9556884d19 Mon Sep 17 00:00:00 2001 From: sastaachar Date: Thu, 17 Aug 2023 15:39:14 +0530 Subject: [PATCH 1/3] Added graphql guide --- modules/ROOT/pages/graphql-guide.adoc | 182 ++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 modules/ROOT/pages/graphql-guide.adoc diff --git a/modules/ROOT/pages/graphql-guide.adoc b/modules/ROOT/pages/graphql-guide.adoc new file mode 100644 index 000000000..79d714734 --- /dev/null +++ b/modules/ROOT/pages/graphql-guide.adoc @@ -0,0 +1,182 @@ += GraphQL quick setup guide +:toc: true + +:page-title: GraphQL Guide +:page-pageid: graphql-guide +:page-description: ThoughtSpot Guide to GraphQL + +This section serves as a quick guide for initiating your interaction with ThoughtSpot's GraphQL endpoint. +We will be using Apllo client to interact with thoughtspot's GraphQL endpoint. + +== Pre-requisites + +Before we proceed, make sure you have a JavaScript environment set up for your application. This requires Node.js, which you can download and install from https://nodejs.org/en/download/. + +Once Node.js is successfully installed, you can initiate a new project using the npm init command. + +== Install dependencies + +* @apollo/client +* graphql + +With npm +[source, shell] +---- +npm install @apollo/client graphql +---- + +With yarn +[source, shell] +---- +yarn add @apollo/client graphql +---- + +== Initializing Apollo client + + +We need to import the following from the apollo client library + +[source, javascript] +---- +import { ApolloClient, InMemoryCache, gql } from '@apollo/client'; +---- + +We can initialize the client in one of the two ways. + +=== Using cookies + +For this method we will utilize the cookies set by the browser for authentication. + +[source, javascript] +---- +const client = new ApolloClient({ + uri: BASE_URL + "/api/graphql/2.0", + cache: new InMemoryCache(), + credentials: "include", +}); +---- + +With the client defined above, we can link up to ThoughtSpot's GraphQL endpoint and run queries. + +Because we're relying on cookies for authentication, it's important to have the cookies set up correctly before we run the queries. + +To make sure the cookies are in place, we need to call the login api once before we run any queries. + +[source, javascript] +---- +client + .mutate({ + mutation: gql` + mutation Login { + login(username: "", password: "") + } + `, + }) + .then((result) => console.log(result)) + .catch((err) => console.log(err)); +---- + +NOTE : You can also use your cluster's secret key here for authentication. + +=== Cookieless authentication + +For this method we need to generate the full access token and use it for authentication. + +let us first create a function to get a fill access token +[source, javascript] +---- +const getToken = async () => { + const fullAccessRes = await fetch( + BASE_URL + "/api/rest/2.0/auth/token/full", + { + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ username: "tsadmin", password: "admin" }), + } + ); + const fullAccessData = await fullAccessRes.json(); + return fullAccessData.token; +}; +---- + +Using this function we can setup our client as follows + +Along with the imported functions above we also need the setContext from the apollo client library + +[source, javascript] +---- +import { setContext } from "@apollo/client/link/context"; +---- + +[source, javascript] +---- +const authLink = setContext(async (_, { headers }) => { + // get the authentication token + const token = await getToken(); + // return the headers to the context so httpLink can read them + return { + headers: { + ...headers, + authorization: token ? `Bearer ${token}` : "", + }, + }; +}); + +// httpLink is the link to the graphql endpoint +const httpLink = createHttpLink({ + uri: BASE_URL + "/api/graphql/2.0" +}); +---- + +Now we can initialize the client as follows + +[source, javascript] +---- +const client = new ApolloClient({ + link: authLink.concat(httpLink), + cache: new InMemoryCache(), +}); +---- + +== Using the client + +Once the client is setup we can use it to run queries. + +[source, javascript] +---- +client + .query({ + query: gql` + query GetCurrentUserInfo { + getCurrentUserInfo { + id + name + } + } + `, + }) + .then((result) => console.log(result)) + .catch((err) => console.log(err)); +---- + + +== Reset store on logout + +Apollo caches our requests so we should ideally reset the store on logout. + +[source, javascript] +---- +client.resetStore() +---- + +To learn more about reset store : https://www.apollographql.com/docs/react/networking/authentication/#reset-store-on-logout + + +== Next Steps + +Above we have setup an basic client to interact with thoughtspot's GraphQL endpoint. + +You can integrate the above with React application as well , to leanr more about it : https://www.apollographql.com/docs/react + From e985a3e0580575d3eac7e5d68cbb069f4c8e9700 Mon Sep 17 00:00:00 2001 From: sastaachar Date: Fri, 18 Aug 2023 08:45:50 +0530 Subject: [PATCH 2/3] Minor changes and fixes to graphql guide --- modules/ROOT/pages/graphql-guide.adoc | 6 +- modules/ROOT/pages/graphql-playground.adoc | 179 +++++++++++++++++++++ 2 files changed, 182 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/graphql-guide.adoc b/modules/ROOT/pages/graphql-guide.adoc index 79d714734..b550ebae4 100644 --- a/modules/ROOT/pages/graphql-guide.adoc +++ b/modules/ROOT/pages/graphql-guide.adoc @@ -6,7 +6,7 @@ :page-description: ThoughtSpot Guide to GraphQL This section serves as a quick guide for initiating your interaction with ThoughtSpot's GraphQL endpoint. -We will be using Apllo client to interact with thoughtspot's GraphQL endpoint. +We will be using Apollo client to interact with ThoughtSpot's GraphQL endpoint. == Pre-requisites @@ -176,7 +176,7 @@ To learn more about reset store : https://www.apollographql.com/docs/react/netwo == Next Steps -Above we have setup an basic client to interact with thoughtspot's GraphQL endpoint. +Above we have setup an basic client to interact with ThoughtSpot's GraphQL endpoint. -You can integrate the above with React application as well , to leanr more about it : https://www.apollographql.com/docs/react +You can integrate the above with React application as well , to learn more about it : https://www.apollographql.com/docs/react diff --git a/modules/ROOT/pages/graphql-playground.adoc b/modules/ROOT/pages/graphql-playground.adoc index cffa259d4..1fcf9e191 100644 --- a/modules/ROOT/pages/graphql-playground.adoc +++ b/modules/ROOT/pages/graphql-playground.adoc @@ -60,6 +60,185 @@ query { Docs:: Each type in the GraphQL schema includes a description field which is complied as documentation. To view documentation, click *Docs*. +== GraphQL quick setup guide + + +This section serves as a quick guide for initiating your interaction with ThoughtSpot's GraphQL endpoint. +We will be using Apollo client to interact with ThoughtSpot's GraphQL endpoint. + +=== Pre-requisites + +Before we proceed, make sure you have a JavaScript environment set up for your application. This requires Node.js, which you can download and install from https://nodejs.org/en/download/. + +Once Node.js is successfully installed, you can initiate a new project using the npm init command. + +=== Install dependencies + +* @apollo/client +* graphql + +With npm +[source, shell] +---- +npm install @apollo/client graphql +---- + +With yarn +[source, shell] +---- +yarn add @apollo/client graphql +---- + +=== Initializing Apollo client + + +We need to import the following from the apollo client library + +[source, javascript] +---- +import { ApolloClient, InMemoryCache, gql } from '@apollo/client'; +---- + +We can initialize the client in one of the two ways. + +==== Using cookies + +For this method we will utilize the cookies set by the browser for authentication. + +[source, javascript] +---- +const client = new ApolloClient({ + uri: BASE_URL + "/api/graphql/2.0", + cache: new InMemoryCache(), + credentials: "include", +}); +---- + +With the client defined above, we can link up to ThoughtSpot's GraphQL endpoint and run queries. + +Because we're relying on cookies for authentication, it's important to have the cookies set up correctly before we run the queries. + +To make sure the cookies are in place, we need to call the login api once before we run any queries. + +[source, javascript] +---- +client + .mutate({ + mutation: gql` + mutation Login { + login(username: "", password: "") + } + `, + }) + .then((result) => console.log(result)) + .catch((err) => console.log(err)); +---- + +NOTE : You can also use your cluster's secret key here for authentication. + +==== Cookieless authentication + +For this method we need to generate the full access token and use it for authentication. + +let us first create a function to get a fill access token +[source, javascript] +---- +const getToken = async () => { + const fullAccessRes = await fetch( + BASE_URL + "/api/rest/2.0/auth/token/full", + { + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ username: "tsadmin", password: "admin" }), + } + ); + const fullAccessData = await fullAccessRes.json(); + return fullAccessData.token; +}; +---- + +Using this function we can setup our client as follows + +Along with the imported functions above we also need the setContext from the apollo client library + +[source, javascript] +---- +import { setContext } from "@apollo/client/link/context"; +---- + +[source, javascript] +---- +const authLink = setContext(async (_, { headers }) => { + // get the authentication token + const token = await getToken(); + // return the headers to the context so httpLink can read them + return { + headers: { + ...headers, + authorization: token ? `Bearer ${token}` : "", + }, + }; +}); + +// httpLink is the link to the graphql endpoint +const httpLink = createHttpLink({ + uri: BASE_URL + "/api/graphql/2.0" +}); +---- + +Now we can initialize the client as follows + +[source, javascript] +---- +const client = new ApolloClient({ + link: authLink.concat(httpLink), + cache: new InMemoryCache(), +}); +---- + +=== Using the client + +Once the client is setup we can use it to run queries. + +[source, javascript] +---- +client + .query({ + query: gql` + query GetCurrentUserInfo { + getCurrentUserInfo { + id + name + } + } + `, + }) + .then((result) => console.log(result)) + .catch((err) => console.log(err)); +---- + + +=== Reset store on logout + +Apollo caches our requests so we should ideally reset the store on logout. + +[source, javascript] +---- +client.resetStore() +---- + +To learn more about reset store : https://www.apollographql.com/docs/react/networking/authentication/#reset-store-on-logout + + +=== Next Steps + +Above we have setup an basic client to interact with ThoughtSpot's GraphQL endpoint. + +You can integrate the above with React application as well , to learn more about it : https://www.apollographql.com/docs/react + + == GraphQL queries and mutations The GraphQL Playground supports `query` and `mutation` operations. Both these types of operations consist of multiline JSON. You can also use copy Curl commands from an API request. From d0af26c04f768daf7709692d2ad599e068311d94 Mon Sep 17 00:00:00 2001 From: ShashiSubramnya Date: Fri, 18 Aug 2023 21:47:17 +0530 Subject: [PATCH 3/3] text edits --- modules/ROOT/pages/graphql-guide.adoc | 46 ++++++++++++--------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/modules/ROOT/pages/graphql-guide.adoc b/modules/ROOT/pages/graphql-guide.adoc index b550ebae4..9497a3953 100644 --- a/modules/ROOT/pages/graphql-guide.adoc +++ b/modules/ROOT/pages/graphql-guide.adoc @@ -5,14 +5,13 @@ :page-pageid: graphql-guide :page-description: ThoughtSpot Guide to GraphQL -This section serves as a quick guide for initiating your interaction with ThoughtSpot's GraphQL endpoint. -We will be using Apollo client to interact with ThoughtSpot's GraphQL endpoint. +This section serves as a quick guide for initiating an interaction with ThoughtSpot's GraphQL endpoint. We will be using the Apollo client to interact with ThoughtSpot's GraphQL endpoint. == Pre-requisites -Before we proceed, make sure you have a JavaScript environment set up for your application. This requires Node.js, which you can download and install from https://nodejs.org/en/download/. +Before you begin, make sure you have a JavaScript environment set up for your application. This requires `Node.js`, which you can download and install from link:https://nodejs.org/en/download/[https://nodejs.org/en/download/, window=_blank]. -Once Node.js is successfully installed, you can initiate a new project using the npm init command. +After Node.js is successfully installed, you can initiate a new project using the `npm init` command. == Install dependencies @@ -33,19 +32,18 @@ yarn add @apollo/client graphql == Initializing Apollo client - -We need to import the following from the apollo client library +Import the following from the Apollo client library: [source, javascript] ---- import { ApolloClient, InMemoryCache, gql } from '@apollo/client'; ---- -We can initialize the client in one of the two ways. +Initialize the client using one of the methods described in the following sections. === Using cookies -For this method we will utilize the cookies set by the browser for authentication. +For this method, we will utilize the cookies set by the browser for authentication. [source, javascript] ---- @@ -56,11 +54,11 @@ const client = new ApolloClient({ }); ---- -With the client defined above, we can link up to ThoughtSpot's GraphQL endpoint and run queries. +With the client defined above, add a link to ThoughtSpot's GraphQL endpoint and run queries. Because we're relying on cookies for authentication, it's important to have the cookies set up correctly before we run the queries. -To make sure the cookies are in place, we need to call the login api once before we run any queries. +To make sure the cookies are in place, call the `login api` before running other queries. [source, javascript] ---- @@ -76,13 +74,15 @@ client .catch((err) => console.log(err)); ---- -NOTE : You can also use your cluster's secret key here for authentication. +[NOTE] +==== +You can also use your cluster's secret key here for authentication. +==== === Cookieless authentication -For this method we need to generate the full access token and use it for authentication. +For this method, you need to request for a full access token and use it for authentication. Let us first create a function to get a fill access token: -let us first create a function to get a fill access token [source, javascript] ---- const getToken = async () => { @@ -101,9 +101,7 @@ const getToken = async () => { }; ---- -Using this function we can setup our client as follows - -Along with the imported functions above we also need the setContext from the apollo client library +Using this function, we can set up our client as shown in the following examples. Along with the imported functions described in the preceding example, you need `setContext` from the Apollo client library. [source, javascript] ---- @@ -130,7 +128,7 @@ const httpLink = createHttpLink({ }); ---- -Now we can initialize the client as follows +Now you can initialize the client as shown in this example: [source, javascript] ---- @@ -142,7 +140,7 @@ const client = new ApolloClient({ == Using the client -Once the client is setup we can use it to run queries. +After the client is set up, run a query. [source, javascript] ---- @@ -161,22 +159,18 @@ client .catch((err) => console.log(err)); ---- - == Reset store on logout -Apollo caches our requests so we should ideally reset the store on logout. +Apollo caches requests, so it's recommended to reset the store on logout. [source, javascript] ---- client.resetStore() ---- -To learn more about reset store : https://www.apollographql.com/docs/react/networking/authentication/#reset-store-on-logout - - -== Next Steps +To learn more about reset store, go to link:https://www.apollographql.com/docs/react/networking/authentication/#reset-store-on-logout[https://www.apollographql.com/docs/react/networking/authentication/#reset-store-on-logout, window=_blank]. -Above we have setup an basic client to interact with ThoughtSpot's GraphQL endpoint. -You can integrate the above with React application as well , to learn more about it : https://www.apollographql.com/docs/react +== Next steps +After you have set up a basic client to interact with ThoughtSpot's GraphQL endpoint, you can integrate it with a React application. For more information, see link:https://www.apollographql.com/docs/react[https://www.apollographql.com/docs/react, window=_blank]. \ No newline at end of file