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.
Goals
- Learn about the common HTTP methods (also called verbs) that are used in web APIs and web services.
- Examine a simple web API in asp.net core 3.1 so that you can identify the methods in the controller.
- Learn how to use curl from the command line.
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 -X POST --header "Content-Type: application/json" -d '{"date":"2020-08-26T00:00:00","temperatureC":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.
PUT
The PUT method replaces all current representations of the target resource with the request payload. Unlike POST that is only submitting an entity, PUT replaces all representations of the resource. How you do that, is again up to you as the programmer. The difference in my example is that if a resource with the date in question exists already we will delete it before adding the resource included in the PUT request.
If you look at the C# code, you will notice there is no possibility of returning false. We could make this particular method void. Let's try it as is:
curl -i -X PUT -H "Content-Type: application/json" -d '{"date":"2020-08-25T00:00:00","temperatureC":15,"summary":"Cool"}' http://localhost:4829/weatherforecast/PutForcast
PATCH
PATCH allows us to partially modify a resource. Given these semantics, we can consider it a necessity that the object already exists. I.e. you can't patch a non-existent tire. For us this means that we there must exist a resource with the same date. Take a look at the C# code and the try the following:
curl -i -X PATCH -H "Content-Type: application/json" -d '{"date":"2020-08-25T00:00:00","temperatureC":15,"summary":"Cool"}' http://localhost:4829/weatherforecast/PatchForcast
Summary
In this lecture we learned about HTTP verbs that are commonly used in web APIs.
- You should know the HTTP methods/verbs and what each one does.
- You have been given a asp.net core 3.1 web API example to play with that works across the Windows/Mac/Linux platforms, so you should be able to identify these in code.
- You should be able to use curl effectively from the command line.
Additional Citations/Resources: