GET & POST Requests Controller

[00:00:00]
>> Josh Long: Now I think it's time to build up a simple sort of HTTP controller, our own service based on that. And we've already seen some of this so far. We've looked at Spring MVC so far, but let's just rehash that point here. Class users controller. I'm going to inject the declarative user client, add that to the constructor, and I'll just create an endpoint here called users.

[00:00:28]
And this feels like a bit of a waste, but okay, I'm going to just call the client. It in turn is going to call the other service. And by the way, since I am calling another service, what's the first thing I should do? Virtual threads enabled is true.

[00:00:40]
Always remember, do that first, okay? We don't need to rerun that code that prints things out. Okay, so localhost 8080 users. There we go. This is my service, which in turn is calling the other actual service and getting all the data back. It's a bit of a silly example, but you can see how easy it is to do that.

[00:01:09]
So I'm making an HTTP get request. You know how you can tell? It's because it says GetRequest or GetMapping, okay? Now obviously if you're doing an HTTP post, you can do post mapping. You get the idea, right? And there's all sorts of sort of, create user. I can have a request parameter here, right?

[00:01:30]
Request parameter, string name. I can do a path variable, you know, int id, and then that means I have to have it in a template there as well. Okay, you can get access to the underlying raw HTTP servlet request, servelet request if you want, just inject that as a parameter.

[00:01:51]
So these parameters, you can decorate your controller methods with as many parameters as you want. For all these different kinds of verbs, their lowest level annotation is actually request mapping. Request mapping in turn has a field called method. So, this is semantically equivalent to this. These two are the same, okay?

[00:02:20]
One is just a stereotype, a meta annotation for the other. Okay, well, what else do we got? So that's basic Spring MVC. It says, I told you, we have this meta annotation mechanism, right? You can compose annotations and create your own annotations. Because the goal is for the code to be idiomatic.

[00:02:39]
To talk about an ubiquitous language in domain modeling, right? And so we want that here. Spring is meant to be a framework for building frameworks. It's meant to be a tool upon which to address different verticals. And a big part of that is you, it's your code, it's your domain, right?

[00:02:54]
It's very natural then that you'd create your own annotations and your own component model that would be natural in expressing your domain. So you might wonder, if that's so easy, then why, if I'm building a REST API, did I not use or why do we not have a annotation called RestController, right?

[00:03:11]
And we do, actually, so RestController is that. And then that in turn is a meta annotation of controller and response body, and that controller is a meta annotation of component. So there's a train derivatives cascade. But I don't like calling things restcontroller unless they're actually restful. And this gets into a little bit of pedantic stuff here, which is to say that what I've been doing this entire time is not REST, this is HTTP, right?

[00:03:40]
It's not actually REST unless it's served in the Champagne region of France. You need to adhere to hypermedia, right? The idea, when Dr. Roy Fielding talked about REST in his doctoral dissertation back in 2001, or whatever it was, he talked about the idea of hypermedia links, right? When you look at an HTML document and you get a link, the link has a rel, and it has the rel tells you what the nature of the link is, and then you have the actual URL itself.

[00:04:12]
The rel is the important part, it tells you why you would want to click on this. We don't use that very often. But for example, the link tag, when you use that for CSS, it says rel equals whatever text, CSS or whatever that tells the browser agent, hey, this resource at this URL is what you need to style the document you're looking at.

[00:04:30]
So it's an offshoot. It's saying to the browser, hey, you can go to this URL to get styling information. You should. And the way a browser knows it's styling information is by looking at the rel. Well, imagine if all of our APIs were built that way, right? Imagine if all of our APIs had menus of things that are germane to the thing at hand.

[00:04:49]
So there's a great book called REST in practice by Dr. Jim Weber that was written, I don't know, 2011, something like that. And it was basically, it took the idea of, have you ever read Enterprise Integration Patterns? Enterprise Integration Patterns it's a page turner, It's a real page turn.

[00:05:06]
It's 1,000 pages, I keep it under my pillow, read it to the kid, it's amazing. And it defines a lingua franca of enterprise application integration. And it was written in 2004 and in that book, Gregor Hope, who's the Bobby Wolf and Gregor Hobe Gregor talks about. He's got a great blog, he wrote in response to that book called Starbucks does not use two phase commit, right?

[00:05:27]
The idea there is when you go to a Starbucks, this is not a distributed transaction, it's a series of events that happen in succession based on inputs, staged event driven architecture. So you go to the person at the till, they write your order on a cup. It used to be they wrote it on a cup, but now it's all these fancy labels.

[00:05:48]
They write it on the cup, the cup gets moved onto the bar where the person who makes drinks is, or it gets moved to the blending station. And then those drinks with the cup and the order and the name gets moved to the final place where you collect them.

[00:06:03]
There's multiple steps, right? The same order might go into multiple places and at each step there's a possibility for failure and having to go back. It's not one big transaction, it's multiple steps in sequence. And it's obvious because of the contents of the message where the message should be routed.

[00:06:19]
The message in this case being the cup, the order, okay? The same is true for hypermedia. The same is true for REST. When you go to an API, you should be able to go to forward slash and get a menu of possible options. What can you do with this API?

[00:06:34]
It makes no sense that I can call a refund endpoint if I haven't bought anything, right? That makes the code for refunding orders a lot more complex because I have to defend against an invalid state. But if I wrote my code in such a way that I followed these menus and the menus were dynamic and they only showed me possible navigable sort of states, then I would never get in that situation in the first place.

[00:06:55]
It makes my code a lot simpler, right? So this hypermedia idea was talked about 20 plus years ago. Same thing for your client code, right? If I don't have an option to refund an order, then I in my React app should disable the button, right? I don't have to have constant.

[00:07:12]
I don't have to have the business logic on the client and on the server, right? The server controls the state, it's where the state lives. The server says, hey, this order is not refundable because it hasn't been purchased yet, right? So there's no link to refund. If there's no link in the response, then there's no button that could show it, right?

[00:07:29]
So this is a very, very powerful concept, and it's all around this simple idea of I have links that help me understand where I can navigate to, given the current state.