Eve: Building RESTful APIs with MongoDB and Flask Transcripts
Chapter: What is REST?
Lecture: Core REST principles
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.