diff --git a/modules/ROOT/pages/graphql-guide.adoc b/modules/ROOT/pages/graphql-guide.adoc new file mode 100644 index 000000000..9497a3953 --- /dev/null +++ b/modules/ROOT/pages/graphql-guide.adoc @@ -0,0 +1,176 @@ += 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 an interaction with ThoughtSpot's GraphQL endpoint. We will be using the Apollo client to interact with ThoughtSpot's GraphQL endpoint. + +== Pre-requisites + +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]. + +After 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 + +Import the following from the Apollo client library: + +[source, javascript] +---- +import { ApolloClient, InMemoryCache, gql } from '@apollo/client'; +---- + +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. + +[source, javascript] +---- +const client = new ApolloClient({ + uri: BASE_URL + "/api/graphql/2.0", + cache: new InMemoryCache(), + credentials: "include", +}); +---- + +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, call the `login api` before running other 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, 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: + +[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 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] +---- +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 you can initialize the client as shown in this example: + +[source, javascript] +---- +const client = new ApolloClient({ + link: authLink.concat(httpLink), + cache: new InMemoryCache(), +}); +---- + +== Using the client + +After the client is set up, run a query. + +[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 requests, so it's recommended to reset the store on logout. + +[source, javascript] +---- +client.resetStore() +---- + +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]. + + +== 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 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.