This course has been updated! We now recommend you take the API Design in Node.js, v4 course.

Check out a free preview of the full REST & GraphQL API Design in Node.js, v2 (using Express & MongoDB) course:
The "Mutations Overview" Lesson is part of the full, REST & GraphQL API Design in Node.js, v2 (using Express & MongoDB) course featured in this preview video. Here's what you'd learn in this lesson:

When you need to make changes to the data source you can add a mutation. Mutations need their own resolvers.

Get Unlimited Access Now

Transcript from the "Mutations Overview" Lesson

>> Scott Moss: Anybody remember what I said mutations were?
>> Speaker 2: They're updating the database.
>> Scott Moss: Yeah, you want to mutate your data source, or data sources, or whatever. Yeah, you basically wanna make a change back there somewhere, so the equivalent to REST would be put, post, delete, right? So use whenever you need to make a change to a data source as in the word mutate, that's why it's called mutations.

[00:00:25] You're mutating a data source. If you're not gonna mutate a data source, then you're probably only asking for data so use a query instead. Useful for post, put, delete requests. They usually take arguments, otherwise I wouldn't know how you would you know unless you just had a persisted mutation that always did the same mutation every time.

[00:00:47] But if that was the case, you wouldn't be mutating something that was constantly changing. So I think most of the time, all of these will always take arguments. I have never run into an example where I did a mutation that did not take an argument. If you do, then you could probably get a way to adjust a query.

[00:01:01] So think about that, think about what your client needs as a response from the result of the input. This one's important because the community really hasn't figured out what should you return from a mutation. That's because it depends on your app. Think about this, we have a REST API, right?

[00:01:18] Now let's say from your to do app, you issued a post request, you create it as a do item. What do you expect to get back from that post request?
>> Speaker 3: Creative resource.
>> Speaker 4: The id?
>> Scott Moss: The id, you said the creative resource? You see what I mean, you never know, it depends on what your app is.

[00:01:35] Maybe your to do app needs the full to do back. Maybe it only needs the id. Maybe it needs to say okay, I don't know. That's what this is saying. Depending on what your app needs back, just make sure you respond appropriately. Because a mutation does the same thing.

[00:01:49] You create something but you also ask for something back. So it's like a creation and a query at the same time. So although you will be creating something, you need to say well, this is what I want back. So depending on your app, you need to make sure you're getting back what you need back.

[00:02:01] I would say for most clients using GraphQL, you'll probably need back at minimum the id and the changes that you made. Because most GraphQL mutations probably use something locally that uses caching, like Apollo or Relay. And to update your local cache, you need to reference to the thing to update and that's usually consisted of the id plus something else.

[00:02:20] And then you also need the things that you updated. Because most likely that cache is reflecting what's on your UI. So if you don't update that cache with what you just updated or what you just created, then now your UI is out of date. So most likely you would need the id plus the things you updated, minimally.

[00:02:37] Ideally you would just ask back for the whole thing. Just give me back the whole thing, the whole thing, even stuff I didn't update. Just give me back the whole object. So that's what I would say. You can only do one mutation at a time, and you might be asking like okay, we can only do one create a time.

[00:02:50] Actually, you could do more than one create at a time, I forgot to mention that. And what that looks like is, it's not really that complicated. It's basically saying you could do this, so if I'm doing a query of allPlaylists, let's just keep it simple. I could also, right underneath it, I could say, I wanna do Song too.

>> Scott Moss: And then I also wanna do allSongs.
>> Scott Moss: You could do that. And obviously I get an error because stuff's messed up. This one's messed up right here.
>> Scott Moss: There we go. So you can do more than one query in one query. Does that make sense? This is one request that I did and I did multiple queries.

[00:03:33] And they're all based off the name. So again, you could alias these and say these are the playlists.
>> Scott Moss: These are the songs. And then with that when you run this,
>> Scott Moss: You'll get playlists and songs, pretty cool. So you can't do this with mutations. You can only do one mutation.

[00:03:56] You can't do many of them. And they must also have resolvers. So they're not different than queries, you also still need to find some way to resolve these. Because one, you need to mutate the thing you're trying to mutate, and then you also need to send back what the client is asking for.

[00:04:12] So they also have to have resolvers. I'm gonna walk you through how to make a mutation from the client's perspective. Then we'll walk through how to create a mutation on the schema perspective and then you'll create some mutations. And then from there, you should be able to come in graphical, create some data, and query some data yes?

>> Speaker 5: So if you do multiple queries and one of them returns an error, do you get data for the one that was successful and an error for the one that wasn't?
>> Scott Moss: It depends on your set up by default, you should, so let's go back to what I had here.

[00:04:46] So this one is definitely going to throw an error because this is not a real id. And right now it's saying no, you don't get anything. So I guess by default, you're not just gonna get anything, it's more like a transaction. Where it's like in a database if you roll a transaction, if one thing fails it completely just stops.

[00:05:01] So in this case, we have a error from this one query, so the whole thing errored. You could prevent this if you want, it's totally up to you, but yeah, I guess depending on our implementation using a Apollo GraphQL, yeah, you get one error, everything's done.