Connecting to a Workspace GraphQL API

* This is an automated transcript. Please excuse inaccuracies.

‍

Hi everyone, so in this video we're going to be going over connecting to your workspace API. And to get that off one thing I would like to do is remind everyone, that Graph QL is no different than an HTTP POST request. After we get past a little demonstration which is connecting to our workspace through a curl command, then we'll jump in to actually writing JavaScript scripts that communicate with our API.  

Let's jump right to it.  

So, first off here's is the quick demonstration so right here in a text editor I wrote out a curl command which sends a post request to a workspace endpoint that I've defined. And in here we're just saying that the application or the content type is application JSON. We are actually creating an authorization header it which is passed in an environment variable to authenticate our request and then we're adding this query or this string as the data for our post request. And if you look at this you can see it has a query key and then a graphic QL query that we've written out which was getting all the to-do items and their descriptions. So, if we take this and post it into our terminal and run it, we can see that sure enough, we just created execute a Graph QL using a curl command. So, keep this in mind whenever you're looking at different ways of executing or running Graph QL queries. At the end of the day all that's happening in the background is a post request is getting sent to a Graph QL API.  

Now let's jump into actually writing scripts or using JavaScript to run, queries, mutations and anything else that we might need to do with our Graph QL API. To get going what I'm going to do is close out of this, don't save it… excellent! Clear my screen and then move into my code directory. We're going to create a new folder right now which is going to be called “Graph QL connections demo”. Okay so let's move into that demo and inside here we're going to in it a new NPM package. And so, let's use NPM on it and this is because we're going to have to require a few different dependencies or we're going to want to require a few different dependencies for helping us run those queries. So, NPM.net and we can just accept all the default for the package.json file. And once that is created, cool, let's just create a new file called index JS. This is where we're going to write our JavaScript. And all we're going to do right now is install one package which is, NPM install, Graph QL request - Jasmine and we're just going to save it to our package JSON file. Cool! That went really fast and now what we can do is we can run some ole or just open this directory up in your preferred text editor; I'm using sublime.  

So, now here in our script we're going to start writing out or we're going to start by requiring the module within the Graph QL request package that we required. So, we don't have Babel or anything like that setup, so what we're just going to do is use good old-fashioned JavaScript require to get that get that module into our script. So, let's say, Const and we'll just call it “GQL”- oh actually one second, I have to open the index KS file… cool. So, if we said, “Const GQL client” that's just the name that we're giving it and we're going to set that to require the Graph QL, request library and from that get back a Graph QL client module- cool. So, this module right here is going to help us run our request by setting up a client with which we can communicate to our API, and to do that what we need to do then is we need to make sure that we have a few things.  

First, we're going to make sure we have our endpoint right and so the endpoint is something that every 8base workspace is assigned; it's assigned a unique endpoint that you can use to communicate with your API. And so, if we shoot over to our 8base workspace we can see that here on the data we have the endpoint here and we can just copy that; however, you can get it in many places in the workspace so whatever is best for you. So, cool, I'm just going to add that workspace URL right here and then what we're going to do is start by creating a new instance of Graph QL client.  

Actually, one thing that I forgot to mention before we create the Graph QL client, we're going to hop back to our workspace and actually generate an API token to authenticate our requests. If it was an open API, meaning that you gave public access to it, you wouldn't need to do this step. But most the time we are doing secure requests between the API, so we might as well go over it. So, if I go to settings and I go to API tokens I can add a new API token. I'm going to call this one, “delete immediately”. And then you can assign the role or the rights that the token has. So, I'm just going to say that this token has administrative privileges for any request that it's making. Cool. So, I'm going to copy that token and now if I go back into my script I can just say, “add this token here const token” and “add that”.  

So, now we're going to create a new instance of a new client that we can use. So, to create our client first what we're going to do is we're going to assign it where it's going to be a constant, so we'll just name this “client” and then we're going to create a new GQL client this is the name that we gave it. And the first argument we're going to give it is our endpoint this is where it's going to send our requests to. And then the second argument that we're going to give it is options one of those being headers, which we can give a default header of authorization and this will be our bearer token. So, then if we do bear and pass in our API token as the bearer token this will this wall authenticate our requests using the token that we generated. If this was let's say you're got an application there's a logged in user the ID token would be the token that you pass it and then everything would be scoped to that user right; so this is just the simple way that we use bearer tokens to authenticate requests between the application that is requesting information or send the information to the API, so that the API knows who is performing those requests.  

So, cool, let's now actually write out a query to use this client. The query that you write will obviously really this depends on the workspace that you set up as these things are dependent on the data model that your workspace has. However, since we have a workspace that we're handling a workspace right now that is for to do's, it has boards and to-dos related to boards, we're just going to use that domain for the sake of these examples. So, first off let's just create a query that lists out all the boards that we have. So, if we type out boards query and then we create our Graph QL query which is going to be a query and then we want a boards list and for each board- we actually first want know the count and then for each board that we get back, we want the ID and the name of that board. Cool! So, that query will work for us.  

Next what we can do is, then we're going to create an asynchronous function. So, let's just say call this “exec” and we're going to pass it a or it's going to equal an async function that has a block cool. And here what we're going to do is we're going to take our client and we're going to run request on the client, giving it our board's query. All right and so if we await that response and assign it to a variable called, “RESP”, we can then once it's done console.log the result. Cool, so let's open up our terminal and run this and see what we get back. Actually, quick thing before we do that- we have to make sure it actually runs, so just let's execute the function at the end of our file cool. Now this is good.  

So, I readjusted my screens a little bit so that my terminal and text-editor are side by side. And so, like I said now if we run node index.JS, so that we execute this file we can see that we give it a minute and cool it console logged out our response which is a boards list. We have two boards and both of those are objects that are being stringified as a seen for the terminal output alright. So, right now we were able to successfully run a request that's authenticated; however, as you can see that this is just a really static request right here meaning that no variables or anything are being passed to it.  

So, what if this was a mutation for creating the new board and we wanted to run board create which obviously needed to accept a data argument with the board's data which would be a name. And then in response, we only would want back the ID or it created the name. How do we get a variable name here? So, what we can do is we on our mutation we can define the arguments that accepts. So, for example, this accepts name of type string and it's required. And then right here we give it that variable, so that that gets injected.  

But wait still, how do we get the variable there? Well it's pretty simple. So, right here we're going to rename this to “board create mutation”. Let's copy that. Let's give that to our request that we have here and then let's say that this takes a variable called “name”. Alright and so then in here let's name our board, “my newest board”. So, that's the argument that we're passing to our function. So, then right here what we can do is that's the second argument, we get to pass it the name; since it's a variable. If you're not familiar the syntax, this is short for the same thing as if we did name, but it just creates the object as needed.  

So, cool, now what we have is we have our new mutation which is board created and it takes an argument type string called “name” and we're passing it that variable as the second argument to our request all right. So, let's save it and now let's run this, cool. And boom it created our board, gave it an ID and the name the board or returned the board's name by newest board.  

All right, I hope that this gives you a really good idea of how you can get started writing scripts that communicate with your API in JavaScript. In future videos we can do this in any language, Python, Ruby, even more curl command examples. However, remember that once again under the hood all Graph QL requests are, a post request that sends the query as the post requests data to your API which then interprets it and sends back the information that you are requesting.  

If you have any questions, please feel free to leave them in the comments of this video as well as check out any links that I'm adding to the description of the video for further learning about connecting to your API. I hope you have a great rest of your day and thanks for watching.