RESTful and HTTP APIs in Pyramid Transcripts
Chapter: What is REST?
Lecture: Introduction to RESTful services
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
In this chapter we're going to look at what makes a service a restful service, what are some of the core building blocks
0:09
like http status codes, http verbs and so on and we'll compare and contrast restful services with the broader service landscape.
0:18
Generally speaking, restful services are services built upon http that follow the restful principles,
0:26
and you want to think of this more as a spectrum of options, how restful are you, not yes it's restful, no it's not.
0:34
So the most important thing is that we're communicating over http, we have a service, it's using http or https
0:43
and it's explicitly using all the concepts and mechanisms built into the http itself, so http status codes, the verbs, get post put delete,
0:54
content types both for the inbound data and the outbound data, there are many services that have been built
1:00
that technically use http as the transport layer but they ignore all of these things, and they layer their own concepts on there,
1:05
those are not restful services. Next, the endpoints that we're talking to are URLs and this typically means that when we design our service
1:13
we're thinking in terms of nouns, so maybe I'm designing a bookstore and I might have /api/books
1:19
I wouldn't have /api/getbooks, or /api/addbooks or even /api/books/add, no, you just have /books and you apply the verbs,
1:32
http verbs to them to modify them, do you want to get all the books, we'll do a git request against /api/books;
1:39
do you want to add a new one, let's to do a post or a put to that, all right. So you combine these http concepts, codes and verbs,
1:47
and you apply them to these endpoints, so really the takeaway is when you design these APIs,
1:52
you need to think in terms of nouns, what are the things being acted upon in your system. The responses from your request should be cashable
2:01
not every single type of request that's made you a service will be cashable but in general, when the http verb says it can be cashed,
2:09
it should be possible for it to be cashed, like a get request against /api/books may be intermediate proxy server
2:16
should be able to cash the response from there. We also want to make sure your system is a layered system
2:22
and what that means is your service clients they cannot see past your API. If your service is calling through to other services,
2:33
and it's composing them to basically make up its own functionality that should be opaque to your consumers.
2:40
Your services should also be stateless, you should be able to make requests get a response and that's all you need to know,
2:48
what goes in, what goes out, you don't like log into it and then do a bunch of operations and then log out, right.
2:54
If you have to carry that authentication, maybe you have to pass some kind of token as a header value or something like that.
3:00
Mini restful services support content negotiation, so let's take our book example /api/books/one might give us book one.
3:09
Well how do you want that, do you want that in xml, do you want it in json, do you want the picture that is the cover page?
3:15
Well how do we know, you could have a bunch of different end points but typically these restful services will support content negotiation
3:22
so if I make a request to that url and I specify I want json well I should get a json representation of the book back; but, if I specify one image png
3:33
maybe I should get back the cover picture for that book, so that's content negotiation. Finally, we have a thing called hateoas
3:41
or hypermedia as the engine of application state. Now, this is used less but some restful services do make use of hateoas,
3:48
and the idea is I make a request just to the service, in that response maybe I have other URLs that the current state of the service
3:58
my interaction with it maybe I can follow those further so I go hey book store, what do you got; and it says well, I have /books and I have /authors,
4:09
and if I follow /authors maybe it says well, here's a bunch of the people that you go look at, you could maybe add a new one, things like that.
4:16
So this sort of dynamic response and traversal is very much like the web works now you don't go to like cnn.com/ some long url,
4:26
you just go to cnn.com and you look around and it tells you what the current news items are,
4:32
you click on them, you go into them further and you see maybe the related items that's hateoas, but think of that at the service layer.
4:38
So remember, I said you want to think of this as a spectrum, the more of these you include the more restful your services are.
4:46
You will run into some folks that say if you don't have all of these and maybe something I'm maybe forgetting, then your service is not restful,
4:53
and that's one way to see the world but I think it's a little too black and white,
4:56
the more of these that you adopt the more restful that your service is. You start with a basic http service and you build restful principles into it.
5:04
So I would say most services probably make it down to 3 to 5, 6 and 7 are possible, 6 is certainly used some of the time,
5:15
7 is used but it's the least used of all of these.