Eve: Building RESTful APIs with MongoDB and Flask Transcripts
Chapter: What is REST?
Lecture: Core REST principles
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
So what is Rest all about? At conferences or even while talking to my colleagues I am often surprised by how much confusion there is
0:10
even to these days about what really Rest is. In this section we're going to talk a little bit about Rest and RestFul web services
0:18
just to make sure that we understand what kind of service we're going to build with Flask and Eve. The first thing you need to understand and embrace
0:25
is the surprising fact that Rest is not a standard and also, it is not a protocol.
0:32
Rest is more really an architectural style for networked applications. Now, architectural style may sound cool and probably is
0:41
because by not imposing hard to use, it allows for great flexibility. On the other hand, quite frankly, it sucks.
0:51
Probably, on the internet, there aren't two APIs who share the same interface or behavior, most of them however have tier
1:00
in some way or another to Rest principles. So let's review a few of these important principles. First, and probably the most important is the resource
1:11
or the source of a specific information. By the way, in Rest terms, a web page is not a resource it is rather the representation of a resource.
1:21
If you access your Twitter timeline for example what you are seeing there is a representation of the thoughts
1:27
expressed by the people you are following; second important principle is the global permanent identifier, global being key.
1:35
URLs allow us to access the very same resource representation from any place in the world which is not a small feature if you think about it.
1:45
Third, standard interface. Rest was defined in the context of http and in fact, https are very common standard interface
1:54
but very few people know that Rest could actually be applied to other application layer protocols. There is also a number of constraints
2:04
that RestFul web services are supposed to be following stuff like separation of concerns, stateless, cacheability, being layered systems etc.
2:16
We will get back to these in a few minutes. So in a way we could say that the worldwide web is built on top of Rest
2:24
and it is meant to be consumed by humans while RestFul web services are also built on Rest and are meant to be consumed by machines.
2:35
So let's review these Rest principles. The most important thing is that we're communicating over http we have a service, it's using http or https
2:47
and it's explicitly using all the concepts and mechanisms built into the http itself. So status code, verbs such as get, post, put, delete,
2:58
content types, both for the inbound data and the outbound data. There are many services out there
3:04
that have been built technically on http as transport layer but they ignore all of these things and they aren't RestFul services at all.
3:15
Next, the endpoints that we took into our URLs and this typically means that when we design our service we're thinking in terms of nouns.
3:25
So maybe I'm designing a bookstore and I might have a books or works endpoint I wouldn't have a get books or add books or even books-add,
3:35
no, you just have one single books endpoint and you apply the http verbs to modify them. Do you want to get all the books?
3:44
We'll do a get request against books endpoint. Do you want to load the new one let's do a post request to that endpoint.
3:53
So you combine these http concepts, codes and verbs and you apply them to these endpoints so really, the take away here is when you design these APIs
4:02
you need to think in terms of nouns and what are the things being acted upon your system. Responses for your request should also be cacheable
4:12
if the responses are cacheable you get a huge performance boost like in a get request against the books endpoint
4:19
it might be served by an intermediate proxy server that cached the same response beforehand. We also want to make sure that our system is a layered one
4:29
and what that means is that our service clients cannot see past our API surface. If our service is calling through other services
4:38
and it's composing them to basically make up its own functionality, that should be opaque to our consumers. Our services should also be stateless
4:48
we should be able to make requests, data response, and that's all we need to know. We don't log into the service
4:56
and then do a batch of operations and then log out. If you have to carry that authentication maybe we have to pass some kind of token
5:03
as a header value or something like that. RestFul service should have support for content negotiation so let's take our book example,
5:12
the books-1 endpoint might give us book one. Well, how do you want that? Do you want that in xml, do you want that in Json,
5:20
do you want maybe the picture that is the cover page? We could have a bunch of different endpoints but typically, these RestFul services
5:28
will support content negotiation, so if we make a request to that url and we specify that we want Json,
5:34
well we should get the Json representation of the book back, but if we specify one image png
5:42
then maybe I should get back the cover picture for that book. So that's content negotiation. Finally, we have a thing called HATEOAS
5:52
or hyper media as the engine of application state. Now this is less used, but some RestFul services do make use of HATEOAS
6:00
and the idea is that I make a request to the service and in that response, maybe I have other URLs relative to the current endpoint,
6:09
in my interaction with it, maybe I can follow those URLs further, so I go like, hay bookstore what do you got
6:16
and it says well, I have books and I have authors and if I follow authors, maybe it says well, here is a bunch of people that you can go look at etc.
6:27
Just think of a HATEAOS as a way for clients to explore and navigate the RestFul service by following its links.
6:35
Alright, we've seen a number of constraints and features that RestFul services are supposed to be providing to clients.
6:44
There are a lot of them as we've seen, some are more complex than others, but the good news is that when you build a service on top of Eve,
6:52
all of these features and constraints are supported and already provided for you. You can, of course, switch some of them on and off,
7:01
but in general, Rest assured that the web service you're going to build on top of Eve is going to be a fully featured RestFul web service.