This workshop will be retired on May 1, 2025.
Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll
Preview
Start a free Courses trial
to watch this video
Versioning allows communication of state through headers. Spring Data REST uses ETags to accomplish this.
Learn more
Related Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign upRelated Discussions
Have questions about this video? Start a discussion with the community and Treehouse staff.
Sign up
Now that we have some
tools at our disposal.
0:00
We can take a closer look at the responses
that are being sent back from our API
0:02
continuing our quest to
be a good API citizen.
0:06
I was thinking about how we should look at
how to handle versioning in a spring data
0:09
rest application if the concept of
versioning is new to you it's one of those
0:13
win win things that both your clients and
your server load will appreciate
0:17
versioning allows clients to say,
hey I have some data from you already.
0:21
Has it changed since I last got it.
0:25
Now by knowing this information,
0:27
it helps them by not making
a request when they don't need to.
0:28
And it helps our API,
because we don't need to build a response.
0:32
All this communication
happens from headers.
0:35
So what do you say we get it set up,
and go see it in action?
0:37
All right there is a part of the HTTP
specification that discusses using headers
0:41
known as E tags.
0:46
The E stands for entity there.
0:48
So what it is is a tag that
represents the entity current state
0:51
Serving this e tag from entity
is pretty straight forward.
0:57
All we really need to do is mark a private
field with the version annotation.
1:00
And since we want all of our entities
that we serve up to have this tag,
1:05
we should put this on every entity.
1:08
Wait a second, we should put this on, yeah
yeah, you got it the abstract base entity.
1:11
Okay, so
let's open the file with a new field.
1:16
Let's do it.
1:20
So, we're going to come in here and
we're going to say app version and
1:21
we're just going to make
a private long version.
1:26
And if we come over we restart our server,
if we flip over to post man.
1:31
And we do a get request.
1:42
Let's do a get request on this courses
here and then look at the headers here.
1:43
And now you'll see that there's
an e-tag and it's set to 0.
1:48
Adding the version field
automatically added this new header.
1:53
and if we update the version.
1:56
This will change.
1:57
Let's make it happen.
1:59
OK so let's make a new
request to make an update.
2:00
So what I do is let's go back
over to our results here.
2:04
Who's going to copy the title
in the URL here and
2:10
let's change this request from a GET,
let's make it to be a PUT.
2:13
So we're gonna do an update.
2:18
And in our request body we'll make it raw,
application.json and that added,
2:21
the header the appropriate header for us,
so let's go back over here to our body
2:28
and we're going to make
you JavaScript there.
2:33
And let's change the title.
2:41
So Java basics reloaded.
2:42
I guess that's a good feature to
show you can save these going to.
2:47
Okay, and let's go ahead and
send this request and
2:51
we'll see that in the headers that
came back there is a new version.
2:55
We got the E tag of one it's been dated.
2:59
So that means that it's
different than what was at 0.
3:03
Now because we are sending this down to
the client they can use what are known
3:06
as conditional headers to check and
see if things are indeed different.
3:11
Remember there's no need to go get
things if it hasn't changed, right?
3:15
So if we imagine a client
sent a get request and
3:19
got the original E tag of zero And
they wanted to see if things changed.
3:23
They could just do this.
3:28
So they could come, let's go flip this
back to, well let's just go get to
3:29
original GET request here and let's add
the new header and they're gonna say.
3:33
So remember our E tag is currently at
one but the client before went down and
3:39
asked for.
3:43
All they know about is zero, so
they're gonna say if none matches zero.
3:46
Okay a little bit weird language there
but, this is talking about the e tag so,
3:51
if it doesn't match zero, what it say so.
3:56
Now when we run this we should get results
cause there are actual results and
4:00
it did return the body came back across.
4:03
But now that we have this and
we wanted to check again to see.
4:06
So now we want to see.
4:09
Hey if go ahead and get this for
me if it's not 1 right.
4:10
If it's not 1, go ahead and get this.
4:14
So that got to 200 okay,
the one before but let's send the new one.
4:16
Boom.
So we got to 304 not modified, cool right?
4:20
No unnecessary work is
done on either side right.
4:24
We don't need to render things and
4:26
they don't need to process what comes back
because nothing's different, cool right?
4:28
Now another useful thing for
4:32
E tags and this is gonna require
a little bit of an imagination.
4:34
So, we know that we have multiple
clients using our API right we
4:37
have like the Android app and
we have the iPhone app,
4:40
we have a web app and let's just think
right now about the Android app.
4:43
So, the Android app went and
made a request and
4:49
they got back The original version,
it says zero.
4:52
So they're stored.
4:55
Okay so this is at zero.
4:56
And then let's assume that a user on
the web application made a title change
4:58
just like we did.
5:02
Like with the put requests there.
5:03
And so now this actual record, this.
5:04
Course's record,
its entity tag is at 1, right?
5:06
But the Android app is about
ready to make an update.
5:10
So, imagine this.
5:13
Imagine that this is coming
from the Android app.
5:14
So they're going to come in here and say,
I'm going to make a put and I'm gonna
5:17
to make a raw put and we're going to call
it, and this is again application adjunct.
5:22
And in their headers here this is from
before in the, so you got this, so
5:29
they're gonna say, I want to change the
title to Java basics Electric Boogaloo.
5:34
So, but what they're interested in,
they're gonna say I wanna update this but
5:42
only if, if it matches zero,
otherwise somebody else has changed it and
5:46
you don't know you might be
making the same change or
5:51
you might be making a change
that invalidates what they said.
5:53
So you wanna check and see I want to do
this PUT request only if it is at zero and
5:56
so when they do a send what's gonna happen
to the android app is they're gonna
6:02
get back 412 Precondition Failed.
6:07
And that helps our Android client
know that the update was blocked and
6:10
that it should update itself
at the latest version.
6:13
Pretty nice right?
6:16
Safe updates across all clients
Just by adding an annotated field.
6:17
This is the framework that
just keeps on giving.
6:22
Yeah one more thing that I thought
I'd point out while we're here
6:26
is that we just aversion to our entities.
6:28
Now there is another practice of
versioning when we're talking about
6:31
rest API and that's regarding
the version of the API itself.
6:34
So, a lot of times you might want to end
up prefixing your API with a new version.
6:38
Like for instance you might
want to have API V1, right.
6:43
So, that is the first version of your API.
6:47
It may be later going to
release an awesome API.
6:49
It's going to be API V2.
6:51
So then you can just release a totally new
API without affecting other users right so
6:53
you can make a whole separate API.
6:58
So let me show you how
to do that really quick,
7:00
the trick is in the application
properties over here.
7:02
If you've just come in and you say,
spring.data.rest.basePath =,
7:08
and then you just say what you want to be.
7:14
So we said that we want it to be /api/v1.
7:17
You've seen this probably
looking at the APIs.
7:19
So let's say that and
let's restart the server.
7:22
Now if we come over here now
it's no longer at courses.
7:28
Now let's do this so
just get over here will do a get to API
7:32
the one and then the rest of our API right
so we added the prefix of API V1 and
7:42
we do a send there it is and you'll see
that all the links now have the new prefix
7:47
as well when they are generated and also
what that means is that the how browser
7:52
moves to not browser off of the route
anymore but API slash view one.
7:57
And what that means is that you can
navigate multiple versioned APIs.
8:04
Pretty great, right?
8:08
Awesome.
8:11
We now got versioning installed and
8:11
now our clients will only
make requests that they need.
8:13
Well, almost, right?
8:16
We need to let them know about it.
8:17
Just because you add a feature
doesn't mean that people using
8:19
your API are gonna know about it or
how to use it.
8:22
Make sure to broadcast in your API
documentation that you support e-tags
8:25
I'm going to shoot off
an email to my team and
8:29
let them know that they
should lean on those e-tags.
8:31
That should make the apps so
much snappier.
8:33
The problem with the client not using
your API as you intended leads us
8:37
right into our next topic.
8:40
What do we do when our API is misused?
8:42
We need to send down some errors and
8:45
we also need to make sure that we're
validating the input we're receiving.
8:46
Let's do that right
after this quick break.
8:49
You need to sign up for Treehouse in order to download course files.
Sign upYou need to sign up for Treehouse in order to set up Workspace
Sign up