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