Create a REST API With Django

2.5 Creating a New Invoice

All right, so our API is beginning to really take shape. But all we're really able to do at this point is get preexisting invoices within the system, which is useful for a while but it will only take you so far. So the next thing that I wanna be able to do is actually create a new invoice within the system. So this is gonna be a first jog into the world of the Django REST Framework and REST APIs, where I'm actually going to be issuing a different request other than a GET through the browser. So this is where we're gonna start to use a tool like Postman. So if you don't already have it, now's the time where you're going to need it. So I wanna go back into my views. And when it comes to typical REST APIs, when I want to create a new resource within my system, I'm typically going to be issuing my requests at the list function here. So within the invoice_list now, this is why I cared so much about this being a GET request before. So now in this case, I want to handle not only a GET request to get information, but I also wanna handle a POST request. And the POST request is the one that we use when we want to create a new object. So we have to make a couple of changes here. The first thing that I wanna do is I wanna tell my api_view decorator here that now I'm gonna handle the GET as well as the POST requests. So now here I have if the request.method is equal to GET then go ahead and do that, but what happens if this is a POST request? Well, we're going to do some similar things, but we've gotta make a couple of changes here. So now, outside of this original if block, we're gonna do an elseif. And I'll drop down a little bit more so it's easier to see. I wanna do an elseif in this case if the request.method is equal to POST this time, then I need to do something a little bit different. Now when it comes to posting data to the server, one of the first things that you want to do is you want to check to make sure that the data being passed in is valid. So the way that we're gonna do that is we're going to go ahead and get our serializer. And we're gonna set this equal to a new instance of an InvoiceSerializer. And what I want to do is I wanna set its data equal to the request that's being passed in which has a data property as well, or the body of that request that's being passed in. So it's going to basically do the reverse almost of what's going on when I'm passing in an object into my serializer and it's creating that data property for me. In this case, I'm going to set that data property for me. And the reason that I'm doing that is because I can use a special function on my serializer, which is .is_valid. So it's gonna take a look at the properties that have been passed in. It's going to try to serialize this and see if this is a valid invoice, which I can then check with this function here. If it is valid, then what I can do now is I can say serializer.save. Now the reason I can do that is because I'm once again using a model serializer, which is really just wrapping the functionality around being able to interact with an invoice. So this save is actually going to translate that JSON string that's being passed in into an invoice object, and saving it to the database. Now if all of that works successfully, then we can simply return a new response. And in this case, we wanna return a couple of things. We want to return the data that's actually associated with that invoice. So this is gonna be serializer.data, which, if everything was saved to the database correctly, will now have an ID. So I will return back this object that was sent to me via the API. I will check to make sure it's valid. I will save it. It will generate an ID and I will send all of that information back. So if the user wanted to then get that invoice specifically, it would then have an invoice or a specific identifier to be able to get that individual resource. And I'm also gonna pass back a status. And in this case, when we create things within our API, we typically use a 201, which is the created response. So I'm gonna say this is going to be 201_CREATED just like that. Now we also have to handle the bad situation to say if the serialized data is not valid. So if I passed in something incorrectly or something that was required that I didn't pass in, then I'm going to return something a little bit different, which is going to be once again another response. But this time I wanna pass back the errors that came along with that attempt to serialize that data. And if you pass in incorrect data to an API and something goes wrong, then you're typically going to get a 400 or a bad request. So in this case, I can set my status equal to status.HTTP_400_BAD_REQUEST, just like that. So let's go ahead and save this. So now we've only modified one function within our views here. We've modified invoice_list to handle a POST now so I can now send data to my API to hopefully create that within my application. So let's go ahead and save this. Let's hop back over to our terminal. Let's quit this and restart it just to be sure it picked up all of our changes and everything is still working. It looks like it is. So let's begin with going back over to Chrome and let's go ahead and check out our invoices again. And now you see something else is popping up on the bottom and that's because we're handling POST requests. Now I could put some information in here and send it off, but I wanna show you how Postman is going to work. So let's go ahead and jump over to Postman, but beforehand, let's go ahead and grab this URL here. We're gonna switch over to Postman and the way that we do that is we're gonna start off on the Builder tab. And I can come into my request builder here and I want to drop down the GET here, I wanna change this to a POST. And I want to POST to this specific URL, to my invoices URL. And I can specify a Body. And I wanna specify a raw body cuz this is what's going to allow me to input JSON. So I am going to create a JSON object here. So I'm gonna pass in a name, and this is all name-value pairs using strings and then whatever the value of the data is separated by a colon. So the name is going to be My newest Invoice. And then the description is going to be, how about just Another description. And then the total is going to be, this time it's gonna be a little bit cheaper, we'll say this is only gonna be $25. And we're gonna say that the paid amount, And this time, this is gonna be fully paid, it's gonna be paid $25. So now we've built all of this out. We can also specify that the Body of this request is going to be JSON. And when we did that, if I were to look back over here now, the Headers, it actually added a Content-Type header. And this is how the API is going to communicate what type of data is coming in is via this Content-Type header. So once everything is done here, you can double check here. This says that this is a bad string, but it looks to me like we are gonna be okay here. So now if I were to hit Send, we're gonna come down here and yes, well here is our error, JSON parse error, Expecting property name enclosed in double quotes. I got a little bit too used to using single quotes and that's what Postman was trying to tell me. So let me just go ahead and update these real quick. All right, so everything now is updated to use double quotes instead this time. And if I were to go ahead and hit Send, I get back an object that now has an id of 3. So now I'm able to create new invoices within my system, and to see that individual invoice, I can copy this URL. I can open up a new tab, and this time I want to get invoice number 3. So I've set up my GET request to use that URL. I hit Send and now I get that individual invoice here with an id of 3. And I can also issue an GET to invoices and now I'm gonna get both 2 and 3 like that. So now, can we not only get a list and get an individual invoice, I can also create a new invoice and get that back as well.