= 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 ([[https://tools.ietf.org/html/rfc7231#section-4|RFC 7231, section 4]] and [[https://tools.ietf.org/html/rfc5789#section-2|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:''' * [[https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods]]