Execute Queries and Mutations on a GraphQL API using Insomnia

Lecturer: [0:00] Here's the GraphQL API we're going to be using to build our News application. You won't need to edit any of this code, but you will need to run this API locally in order to follow along with the course. Let's open index.js and scroll down to the type definition section. Here, we can see that this API will expose three queries and two mutations.

[0:21] For the queries, we have a stories query, which returns an array of stories, and we can see the type definition of a story up here. Scrolling down to the resolvers, we can see the stories resolvers, which will return the array of stories, which are hard-coded here in the API.

[0:41] Because we'll be running this API locally, it will be super-fast. I've also added some one-second timeouts here to make it more realistic to what the API would feel like in production. Next, we have a story query. This is a query that takes in arguments. In our case, it takes in one argument for the ID of the story we want to fetch. It is a mandatory argument, which is denoted by this exclamation mark, and it is of type ID.

[1:12] This query will return a story or null. Because there isn't an exclamation mark here, we know that the return type of this query might be null. Now, scrolling down to the story resolver, we see that we get the ID from the arguments. We do array.find() on the stories array to find the correct story and return either the story or null if a story with this ID doesn't exist.

[1:41] Now, let's jump over to the mutations. We'll be able to create a bookmark for a story using the addBookmark() mutation. This addBookmark() mutation takes a story ID of type ID and returns a bookmark. A type definition for the bookmark is up here. All it has is an ID and a story.

[2:04] Conversely, we also have a removeBookmark() mutation, which takes the bookmark ID. This is the ID of the bookmark, not the ID of the story. It returns a Boolean for whether or not the remove mutation was successful.

[2:19] Lastly, we have a query to fetch all bookmarks, which will return an array of bookmarks. If we scroll down to our mutations, we can see get and setBookmarks(). Here, we have a data.json file. We'll be reading and writing the bookmarks into this JSON file in the file system. For our production application, you will need to replace this with a real database.

[2:44] Let's start by cloning the repository. Let's copy the SSH command and open your terminal and git clone in your favorite code directory. Now, we'll need to cd into the directory and run either yarn or npm install to install the dependencies, followed by yarn start or npm start to run the API. This starts the API on localhost port 3000.

[3:10] To explore the API, we're going to be using Insomnia, which is an API client similar to Postman. If you go to insomnia.rest -- side note, don't be fooled by the URL, they actually have excellent GraphQL support as well, as you'll soon find out -- and go to Get Started for Free, and under the Free tier, click on Download App, where you can download the app for your operating system.

[3:34] After you've downloaded Insomnia, you should be able to see a dashboard that looks like this. From here, let's do Create and a new Request Collection. Let's call it news/api. Once you've created it, if you go back to the dashboard, you'll be able to see your new collection here.

[3:53] Let's click into the collection, and let's start by creating a new request. Let's call this request allStories and change this to a POST. From body, let's choose a GraphQL query and hit Create. For the API, let's type in http://localhost:3000/ and GraphQL.

[4:16] If you've got your API running correctly, you should be able to click on this Schema button here and click Show Documentation. This is something that you get for free because we're using a GraphQL API. What Insomnia is doing is an introspection query into our GraphQL API, meaning that it's fetching these type definitions and automatically converting them into this nice API documentation for us.

[4:44] From the schema, we can see that our API has the three queries and two mutations. To query for all stories, we're going to start with a query keyword, and we're going to name this query allStories. Now, we're actually getting some recommendations for what we can query here. We're going to go with stories.

[5:03] You can also choose which fields of stories you want to query, for example, ID and the title. If I hit Send, I will get a response with data and stories, and this returns an array of all the stories and just the IDs and the titles. Say that I also wanted to fetch the author and the summary, I can just add them to my query and also hit Send. You can see that my results includes ID, title, author, and summary for all of the stories.

[5:39] Let's add another request and let's call it storyById. We'll change this to POST and GraphQL query, and Create. I need to copy the URL from our previous query. In here, let's do query story, and let's name our query, storyById. Let's do story and pass in an ID. Let's query the ID and the title of the story.

[6:09] If I go back to my allStories query, and I'm going to copy the ID for the second story and pass it here, now if I send this query, we'll see that we get just the story that I requested.

[6:25] There is also an alternate way to pass in variables to a query. This is the query variable section. If we create a JSON object, and then do an ID and pass in the ID here, here, right next to our query name, we're going to declare which variables we're going to pass in. Let's do ID, and this will be of type, ID! The name of the variable will be whatever the name is here, preceded by a $ sign.

[6:57] Here, in our query, we can now use these variables in place of the hard-coded values. I can send this query and it'll return the same result. You can also copy a different ID and send this, and now I get a different story.

[7:14] Let's create another request and call it addBookmark, change it to POST and GraphQL query. As before, we can copy the URL from our previous query. We start with mutation. Let's call our mutation, addBookmark, and let's do addBookmark storyId. Let's ask for the ID of the bookmark that was created, and also the story ID and title.

[7:42] Now from our allStories query, I'm going to get the ID of the first story. I'm going to pass it here to our story ID, and I'm going to hit send. You can see that this has created a bookmark for us, and has returned a bookmark ID, the story that's tied to this bookmark.

[8:00] As before, we can move the story ID into our query variables. If we create an object and call this storyId, and pass in this ID, then in our addBookmark, we can do $storyId of type, ID. We can use this storyId in our mutation. If we run this again, we get a response of null. This is because the story is already bookmarked and can't be bookmarked twice.

[8:31] One thing you'll notice, that a GraphQL API will always return 200 OK even if the query fails, because errors are communicated within the query result instead.

[8:41] Let's do another request and let's call this allBookmarks. Let's change it to POST and GraphQL query. As before, let's copy the API here. Let's do, query allBookmarks, and let's do bookmarkId. From the story, let's also fetch the ID and title. If we send this, we can see we have one bookmark, the one we created.

[9:10] If we go back to our allStories query and copy the ID of the second story, then go to our addBookmark mutation, add the second story ID into our query variables, hit Send, now this has created a bookmark for our second story. If we go back to our allBookmarks query and hit Send, you can see that we now have two bookmarks, instead of one.

[9:37] Last thing you want to do is remove a bookmark. A new request, let's call this one, removeBookmark, change this to POST and GraphQL query. Let's copy the API. Here, we'll do a mutation. Let's do removeBookmark and bookmarkId.

[9:57] Let's go to allBookmarks. I'm going to copy the ID of the first bookmark. You need to make sure you copy the ID of the bookmark and not the story ID. In removeBookmark, let's paste in our bookmark ID and hit Send. You can see that removeBookmark returns true, and if we go back to allBookmarks and re-execute this query, we'll see that one of the bookmarks has now been removed.