HTTP and the Methods we use in Web APIs
We all know what HTTP is by now. (If you don't see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)
If I ask you to perform a GET request against www.google.com using netcat, you should be able to do that as follows:
nc www.google.com 80 GET / HTTP/1.0\r\n \r\n
Most of you are familiar with this sequence from your networking class.
GET is the action being requested,
/ is the path to the resources requested
HTTP/1.0 is the version of the HTTP protocol we are using.
- The two Carriage Return / Line Feed (CR/LF) characters added to the end is part of the HTTP protocol that signals the end of the request.
Can you use netcat to do that? If you haven't tried it or haven't succeeded, STOP! Get and do it now or get help before you continue.
HTTP Methods
Although, GET is by far the most used method, it is important to know exactly what it and each of the other methods mean/do.
HTTP Methods (RFC 7231, section 4 and RFC 5789, section 2):
- GET
- HEAD
- POST
- PUT
- DELETE
- CONNECT
- OPTIONS
- TRACE
- PATCH
Of these nine methods, web APIs usually only use GET, POST, PUT, DELETE, PATCH
GET
GET is the method we use to retrieve web pages from a regular web application. But that is not technically what it does. The GET METHOD requests a representation of the specified resource. GET performs no side effect (or shouldn't) and thus makes no change to the state of the resource. That is we use GET to retrieve data and nothing else.
Before we leave GET, let's see how it is used in Web APIs. If you haven't already, download the project provided by your instructor entitled L01_Http_Methods.
Run the application from Visual Studio (should work on Windows, Mac or Linux).
Windows/Mac Download and extract the zip file. Open the L01_Http_Methods.sln in Visual Studio. Push Play.
Linux Download and extract the file. Change directory into L01_Http_Methods/Cptr446_01_Http_Methods and run dotnet run. In my case I had to browse to http://localhost:5000/weatherforcast (but pay particular attention to the port).
There are several tools for testing web sites or RESTful services a.k.a web APIs. One tool that I'm going to use throughout this presentation (and course) is curl. curl is available on both Windows and Unix like operating systems. The examples here are completed in the Windows Subsystem for Linux (WSL). I highly recommend spending a little time with the man page. man curl.
Try it:
curl -i --request GET http://localhost:[port]/weatherforecast
Post
The POST method is used to submit an entity to the specified resource. This often causes a change in application state or data. Notice that this is not saving the entity to a resource, but posting to it. This can be seen more as an remote procedure call than a save/update operation. Never-the-less, it is often used that way and we can demonstrate that now by POSTing to the L01_Http_Methods application. If you review the code, you will notice that I do not allow the POST to overwrite an existing entity.
The code below will cause curl to post some JSON to the server:
curl -i --request POST --header "Content-Type: application/json" -d '{"date":"2020-08-26T00:00:00",peratureC":15,"summary":"Cool"}' http://localhost:4829/weatherforecast/AddDailyTemp- -i says to include the headers in the output,
- -k (if we had it) would accept cause curl to accept any certificate including a self-signed certificate
- --request (or -X) identifies the method or type of request, in this case, POST
- --header (or -H) allows us to add headers. In this case we identify the Content-Type we are sending in as application/json. If we didn't do this, you might get a 4xx error telling you that the media is not supported.
--data (or -d) identifies the data to be posted in the body of this request.
Last is the URL. Notice the path includes a api method AddDailyTemp. If you look at the controller, it contains a method by that name.
Let's WireShark that so you can see what it looks like over the network! (If you are not familiar that, see WireShark)
COMPLETE DEMO
DELETE
DELETE method literally deletes the specified resource. Notice that how we specify that resource is up to you the developer. In our case I am specifying the high temperature for the day, so it makes sense to specify the delete by the date. Notice how similar this looks to our GET method for retrieving data for a single day.
Try it out:
curl -i -X DELETE http://localhost:4829/weatherforecast/DeleteDailyTemp/2020-8-25
If you look at the code, you will notice that the method that does the actual deleting is called DeleteDailyTemp, If you look at the Attribute above the Method it says [HttpDelete("DeleteForecast/{forecast}")]. This is the method that we will call. If we wanted to use the other method, we'd have to do something else. I'll leave that as an exercise for you. This is an example of routing. We will go over routing later, so don't worry about that right now.