RESTful and HTTP APIs in Pyramid Transcripts
Chapter: A nearly RESTful service
Lecture: Introducing renderers
0:01 Now let's talk about how we can vary the response type
0:04 and create different types of renderers,
0:06 the json one has been really great, but what if we want something like csv or xml
0:10 or even images or binary data— all of these things are possible
0:14 in exactly the same way that we're able to render json.
0:17 But let's look at the overall architecture and role of these renderers.
0:21 Imagine here that we have our car details view method
0:24 so this is one that returns all the details about a single car given its id
0:28 and so a request is going to come in an d it says
0:31 get/api/auto/ whatever the id of the car they're looking for is.
0:35 We got to do a little bit of work to juggle things in the web framework
0:38 like go to the matchdict and pull out the car id and things like that,
0:41 but pretty quickly we're going to go to our database and return an object,
0:45 and very likely especially for using an orm or we have a larger application
0:50 where we've put a proper architecture in place,
0:53 this is going to be a native python object or maybe even a full object graph
0:58 in the sense of like it could be a car, the car could have a list of previous owners,
1:02 it could have a list of like repair history, it could be quite a complex thing
1:07 that comes back from the database.
1:09 Now we know that the client that requested this wants that back
1:14 and for now let's say they want it back in json form,
1:17 we can't just return this object right, you know,
1:19 maybe pyramid can convert it to a string, but it would just say you know
1:24 type name at memory address like that's completely useless
1:27 we need something that converts this
1:30 potentially complex object graph into proper json type.
1:34 We'd also like that thing to maybe set the response type to application/json as well
1:38 so that's where the renderer comes in,
1:41 so the renderer is the thing that we're going to hand this object
1:44 it does its magic and then responds in the actual
1:49 whatever it's supposed to render as,
1:51 this one renders as json, so it's going to convert this object graph to json,
1:54 set the content type, our client gets the response
1:57 and is happy and everything's working great.
1:59 So that's how renderers work.
2:01 Now let's look at the few options that we do have as built in renderers.
2:05 They fall on basically two categories,
2:07 the first I would call template oriented renderers,
2:10 now these are really meant for the web side of things
2:13 the web site not the web service side of things,
2:17 so these would include Chameleon, Jinja 2, Mako, right,
2:21 I'm writing some view method it's going to process a request
2:25 maybe go to the database, get some stuff
2:27 and then it wants to return an html page to a browser, right
2:30 so we can set up the renderer to process a Chameleon template
2:33 or a particular Jinja 2 template and give that model off
2:37 to the Ji nja 2 engine and then it will do its magic and outcomes html.
2:41 These are great, they are super important
2:44 but they're not very relevant for our services in the actual api methods.
2:48 Next, we have json, we've played with json exclusively so far
2:52 and json works great, that one is built in and we are happy to have it
2:56 we'll see how to configure it in just a little bit
2:58 we haven't taken it as far as we can, but json is great.
3:01 There's also json p which is json with padding
3:04 it's commonly used to bypass cross domain policies in web browsers
3:08 but remember, we already set up cors the permissions on our site
3:12 so we don't really care or need to use that in our particular application,
3:15 but it's available if you need it in yours.
3:18 And that's it, these are the built in ones, right, basically html templates and json.
3:21 If you want something else like let's say csv, xml, images
3:25 well, are we out of luck, no of course not,
3:30 we'll see really quickly how to build our own for each of those types and more.