Eve: Building RESTful APIs with MongoDB and Flask Transcripts
Chapter: Fine-tuning your REST service
Lecture: Conditional requests
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
By default, all API responses include an etag header. An etag is a hash value representing the current state of the resource on the server,
0:11
and it is useful for a variety of reasons. Clients are not allowed to edit or delete a resource unless they provide an up to date etag
0:21
for the resource they are attempting to update. This prevents overriding items with obsolete versions. Let's see this workflow in action
0:32
here we have a request to patch a specific document. We want to change the last name to a new value, and we aren't providing any etag in the headers.
0:44
By the way, you provide an etag by using the if-match header. But right now, we are sending a simple request with no etag for the document.
0:55
When we try this command, we get back a precondition required error, which means, as you can see here in the massage
1:04
to edit a document its etag must be provided using the if-match header. Here I have a second request where I'm doing the same thing,
1:13
but I'm passing an actual if-match header, but I am simulating that I don't know the current version
1:20
of the etag on the server, just passing around the string here, so let's assume that I actually have a cached copy on my client of this person here,
1:30
but the etag I have is not up to date with the one on the server somebody else updated the document since the last time I downloaded this person.
1:39
If I try to send this patch in I still get an error but it is a different one it is precondition failed and the message is telling me
1:48
the client and server etags don't match. So if I don't provide an etag, I'm not allowed to update the document
1:55
if I provide a wrong one, I'm also not authorized to update the document. Now let's try, here I am doing the same thing
2:05
and I'm actually passing an if-match header with supposedly correct value this etag should match the etag on the server for this person,
2:17
let's try to patch in and we get an okay response and the document has been updated. By the way, the etag is returned and it is a new one,
2:27
because, of course, the hash has changed on the server, so the next time I try an update or a delete,
2:33
I will have to use this etag because this is the most up to date and matches the one on the server.
2:40
This feature is generally called concurrency control, and again, its goal is to prevent clients to overwrite
2:49
the document on the server with obsolete versions. Now, concurrency control is a powerful feature,
2:56
it is especially important when there are many clients competing for updates now depending on your use case,
3:02
you might not want this complexity in your service you would like to be able to disable this feature and have clients to simply perform edit request
3:12
without any need to provide an if-match header, you can do that. Let's go back to our editor and simply disable concurrency control
3:24
by setting if-match to false. If we save, restart, and we go back to our Postman client, if I go back to our original request here
3:36
where I had no header and still performing a patch on a specific document with a new value, if I send this, I should get an okay response now
3:51
and the document has been updated, let's try a get request on the same endpoint last name has been updated.
3:59
All right, we now know how to switch concurrency control on and off by setting the if-match setting to true or false.
4:08
However, these two options are mutually exclusive sometimes it would be nice if clients could actually decide
4:15
whether the server should check the if-match header or not. Well, it turns out that's possible
4:21
and again, it is simply a setting a keyword in our settings file. Let's go back to an active if-match check on the server
4:35
but let's add a new setting and force if-match default value is true. If you set it to false, it will let the client decide
4:46
how the server should behave when our edit request comes in. If the client has the if-match header in its request,
4:54
then check on the etag will be performed by the server. If on the contrary, the request has no if-match header,
5:01
no check will be performed by the server. Lastly, you have the option to change the key used for the etag,
5:08
in Json payload, you might not like underscore etag here, some people have been asking to remove the underscores for example,
5:16
or they want to use a different keyword. You can do that by simply setting etag = whatever value you prefer here,
5:24
for example, simply etag without the underscore, let's save, relaunch, go back to our get request. Etag has no underscore anymore.
5:37
This is probably the right time to mention that you can also change the keys for the other meta fields, like updated and created.
5:46
You do that by setting the date created and last updated keywords in your settings file.
5:54
Here we are again removing the underscore from the the default values.