- Getting Started 5:55
- Introducing Spring Data REST 6:03
- Entities and Repositories Review 9:28
- Abstract Classes 6:48
- Populating and Relationships 15:39
- Paging 7:12
- Exploring Your API With New Tools - Postman 7:55
- Exploring Your API With New Tools - HAL Browser 3:58
- Versioning 8:52
- Validation 8:31
- Adding Users 11:51
- Adding Authentication 10:35
- Authorizing Deletions 6:56
- Events 7:57
- Wrapping Up 1:18
Preview
Video Player
00:00
00:00
Versioning
8:52Versioning allows communication of state through headers. Spring Data REST uses ETags to accomplish this.
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