RESTful and HTTP APIs in Pyramid Transcripts
Chapter: A nearly RESTful service
Lecture: A nearly RESTful service introduction
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
So far, we've built a service, an http service that exchanges json when you do an http get to it. So this is some ways down the road, but not very far
0:12
towards our fully restful service. During this chapter, we're going to fill out almost all the remaining pieces
0:19
to create what I would consider a restful http service; so let's start by examining what we've accomplished.
0:26
Well, we've been able to do a get request to / api /autos and that gives us a list of available cars and their details back,
0:33
if we want details about an individual car, we can do a get against api /autos/ car_id and this will give us the details back about that.
0:43
We have done some http friendly things, for example car ids that we request when the car itself does not exist return a 404
0:50
instead of just maybe an empty json resolved, or like some kind of message in the body that responds saying car not there but actually it's a 200,
1:00
now we're using the web and we're saying 404 this thing does not exist. However, we're only returning json responses
1:07
and just the default minefield version of those. So we're not doing a lot of work around the format
1:15
although if you had to pick one and stick with it json is really, really solid. What's left to do? Largely what we will do in this chapter.
1:23
So if I'm going to group this into one big idea what we have left to do is make this a read/write service,
1:29
what we've created so far is really read only, we can read all the car details or individual car details, that's it;
1:35
what we're going to do is we're going to make this a read only service where we can post new cars to it, we can update cars,
1:41
we can remove cars by issuing a delete and so on. So the first thing we're going to do is allow us to create new cars
1:48
that maybe we want to list our car for sale, so we're going to do a post, http post to / api /autos.
1:54
Once we've created one of these, maybe we want to update it like maybe we've changed the price, maybe it ’ s gotten cheaper
2:00
because it's not selling or we crashed it and has some problem now, we got to update the listing, things like that.
2:07
So we will be doing a http put to / api /autos/individual car id with the new details about the car.
2:15
And, once we've sold it or we decided we don't want to sell it, we can take it down by doing a delete against api /auto/car_ id
2:22
Then we also want to support a variety of response types now it's cool that we can give json back to our clients
2:29
like json is really the most popular and most useful but what if they want csv instead of json for that list of cars
2:36
or what if they want an image for an individual car, not the json describing the car, things like that.
2:44
So we're going to support a variety of different response types through things called renderers and custom renderers we're going to create
2:50
and we are also going to see that the service ultimately will support what's called content negotiation
2:56
so I could do an http get again to say api /autos and indicate in the header using the except type
3:03
hey I want json and the service will automatically determine that and send back json, I could change that and say no, no take that back, I want csv,
3:12
and now the service will return csv formatted text, as the response. And ideally, this happens without us changing a code at all
3:19
just configuring the system differently at the serialization level, so this is all great, however this content negotiation part
3:25
we're going to do this in the subsequent chapter. All right, so let's look at the road map, I've given you these different pieces that make up
3:33
what I'm considering a restful service and we listed them from simple order to more complex or more advanced, let's see how we're doing.
3:40
Well are we using http methods explicitly— yes, sort of, we're definitely using the codes, right
3:46
we're saying a 404 for missing, 200 for success, things like that, there's more to do there, but certainly we're doing this pretty well.
3:53
For verbs, we're really only easy get and for content types we've been ignoring that as well, so we're going to look at leveraging http verbs
4:01
and content types more carefully in our api here. Are we using endpoints as basically url or uri resources, definitely,
4:09
api /autos api /auto/ an individual one, I think we got that one down solid.
4:16
This is cacheable— yep definitely cacheable, it's certainly a layered system and it doesn't know more about what's beyond it,
4:24
so that's fine and it's going to stay that way. I'ts stateless, mostly; now, right now we have a fake database
4:30
and this fake database like regenerates itself each time we restart the service
4:34
so it's really not actually stateless, but that's just because it's a fake database. Pretty soon we're going to implement a real database,
4:41
and then it will be truly stateless, and the only thing it'll depend on is the database, and we can have as many
4:46
web front ends or service front ends as we want talking to the same database
4:49
and we won't have to worry about session and state and those kinds of things. Are we doing content negotiation— not yet, but we're going to,
4:56
like I said, that's going to be in the next chapter. Finally, there's one we're not going to do in this course,
5:01
so we're not going to use this HATEOAS stuff which is very much how the web itself works, the hyper media as the engine of application state
5:08
we're punting, it doesn't really apply to this service that we're creating here, so we're having a little bit more strict predefined url structure,
5:16
and I think that's how most services work and I'm totally fine with that here.