HTTP defines a set of request methods, I like to call them verbs, and both terms are valid. Each of HTTP Verb has its task and is different from others.
Information transport
HTTP Verbs are used to transport information, each of them may have three options to transport data. REST adds restriction, I’ll cover it later when we’ll talk about said Verb.
api/students/1?name=Martin&courseId=1
In example above there are used two transport options. First of all data passed as Path Variable api/students/1. We can pass there which resource we want to work with and some basic filtering, like here student with Id 1.
Second options used is Query Param ?name=Martin&courseId=1. MVC can map query params into C# objects specified by you.
Third options is to pass data in Body of request. Similarly as with query params, MVC can map it into C# objects. Data in Body is passed as JSON.
Body vs Query Param
If both do the same thing why even bother having two of them. Answer is simple, Query Param has size restriction. Additionally we can use Query Params from web browser, where to use Body we need additional plugins or application like Postman. Using Body vs Query Param is more like convention.
GET
As you can say from name, this one is used to get data from our resource. It’s worth to mention that Get shouldn’t change anything in your persistent store. In other words, Get should only retrieve data nothing more.
Here is where Query Params shine. In REST API it’s used to add additional filtering, paging, sorting and more. As I said before it’s great, because we can test our endpoint in web browser.
Additionally Get shouldn’t contain any meaningful information in body. That means it technically can, but you shouldn’t do that. You can find more here.
POST
This verb is used to create new entity in your resource, and save it for example in database. It will change your resource state. Additionally POST can and should contain information in body instead of Query Params, again it’s more like convention.
PUT
We can use PUT to update some element in persistent store. It’s important that PUT updates whole object, having Student
{id = 1, name = Martin, course = IT Basics},
when we send Student
{id = 1, name = Test}
we should update everything, so our new student will look like this Student
{id = 1, name = Test, course = null}.
Same as with POST data should be passed in Request Body.
DELETE
The DELETE is used to remove specified entity. In most scenarios we will pass all information in Path Variable.
PATCH
This one is tricky. It’s used to partial updates, so having our previous example from PUT. If we would use PATCH we would have Student
{id =1, name = Test, course = IT Basics}.
It should update only properties we send. Why I said it’s tricky one? Because it’s not used that often, PATCH isn’t that straight forward like other verbs, there is different syntax for PATCH (it contains difference as a body), I’ll create article about PATCH in near future, so you’ll understand what I mean.
HEAD
The least used. It’s more like curiosity. HEAD is the same as GET but response will not contain body. You’ll get only Headers as a response.
HEAD is used only in specific situation. When you want to information about page but don’t want to see page. For example to check if page exist. I must say, I haven’t used HEAD even once, but still it’s good to know what HEAD is doing. I haven’t used it, but other developer could.
Outro
This is everything you have to know about HTTP Verbs. It’s going to be base for next post, which will be about uniform interface and behavior of REST API. As always I encourage you to ask questions and leave feedback.