Building JSON APIS With Django / Pinax

0 0

all right I would be talking about building a JSON API with Jago and connects I like to say building Jacob Atkins for the modern world because I feel like web application architecture has changed so drastically over the last several years so many years ago when the iPhone was was introduced we had no idea what little device could do it what it would change our expectations fast courts it did it passports of today and we have an app for nearly everything that we're putting on to the web both in a web app is so much more than just the traditional Django Model View template there's so much more that goes into it the view layers becoming more complex and we need to implement api's to let the smarter richer clients be able to interact with our data so before I get before I get started let me talk a little bit about myself here my name is Brian Rosner I lived in Denver Colorado with my wife and we have a baby due in October I work as a chief architect at all darien l darien is a web agency where we build web apps using Django and connects I work on pin ax at work I have the delivers a bill work on connects but also my spare time I'll speak a little more about connects in a moment l darien also recently open sourced a passive platform as-a-service named Cal it's a foundation for our commercial l variant cloud has which was originally named Gondor and quell it selfies as much as what i'm talking about here today and it also helps drive the development for it unpacks and in the api work but enough about me i'm here to talk about 10x API Penix API was built out of some requirements we have or a development project we had a tall variant the goal of Connect CPI was is to provide a few primitives for building a RESTful API using Django and using Django and pin acts that would be implemented hopefully these sorts of hska that we've built for these apps are going to be used without throughout the whole pin apps ecosystem before I get too far into Independence API I'm going to step back and talk about connects itself so px is an open source platform built on Django it it has a standard project layout which which if you're familiar with Django as we all are he would do a J go admin a start project and you get a project and that has some conventions that are already baked into it so packs kind of builds upon that and provides even more convention around things that are more specific such as through our starter projects we have various other projects like a couch social project that kind of are more tailored towards a specific set of requirements you may have for building your site and also these starter projects are made up of reusable apps there's a lot of reusable apps that we have in the Pentax ecosystem and they're all used as the building blocks of these starter projects actually implement the functionalities that are there and then default templates there are a lot of default templates that we provide out of the box with and actually you don't have to worry about spending time well you know various views and the way that they look you can you can rely on some like bootstrap or other CSS frameworks to actually do that stuff for you and you can just focus on on the stuff that makes your site different it's a like I mentioned earlier the reasoning for px API was due to requirements of an old area development project during our discovery and research phase we came across the JSON API specification the specification provided a lot of clarity on building api's it specifically rust restful api it eliminated all the bike shedding that was that came about with how is the JSON payload structured because you can go on and on days about whether or not the key is here or there or how it's really structured and this just takes care of all of that Jason Jason API itself was a big reason why we decided to build parents API daniel roebuck is the obvious obvious choice is a very well structured very well architected app and it does it didn't quite work well when I looked at a lot of the different resources that are available to connect Jason API to Django rest framework and be able to take advantage of all of the components of JSON API such as doesn't relationship to something I'll go a little more into that and I do need to admit there's a little there's a little bit of a hint of not invented here syndrome but I justify it because we wanted to take full advantage of the spec and marry it with an axe in some very specific way is that really only the bill from the ground up approach was going to be able to do so this is an actual flow chart that we had with the development client at all barian I say this is an increasingly common modern application architecture logged you through the experience that I've had with regard to search about actually build not fir for our customers at the top there you'd have to be on the database where all your data lives and it is it's being exposed as an API and traditionally the the view of the application is that a lot of this time a lot of times this is all kind of in one in one code base in one one process but but that's that's changing quite a bit because a lot of times you end up needing to actually split off these front ends as they're there into their own project because you need to implement in a different language and in this particular case it was because we need to implement these front ends specifically the the shop front end in in node react yes and we'd us so looking towards the future of a prod like this it isn't going to be a big surprise when the client comes up and says we need to add in iOS and Android app today it just becomes a new front-end that's able to communicate with the API so a little bit more about JSON API itself there's the the JSON API org is the URL that actually talks about the specification itself there's gonna be a lot more in-depth details available there that I'm not going to get into here the the way that I look at the specification is as an object graph the object the object graph is naturally as a developer you need to be creating these objects in your applications through through the creation of your models that you create your Jenga project etc my specification is optimized it's optimized in a way that creates the efficient writes and you can also design it in a way to have really efficient I'm sorry rich said the backwards yeah enables the efficient reads when you keep resent in a way that makes it great for efficient rice as well for example let's say you have a blog post and the blog post is being requested by your front end in your front end actually needs to display the comments as well well that could actually be turned into two different HTTP requests but that's gonna increase latency for for your front ends so the way that JSON API works is that you can actually use relationships and compound documents to say I want the blog post but I also want its comments or I also want its author all on the same payload so you don't have to go ask for this information over and over again and also JSON API is it's registered with the the internet assigned numbers authority so this actually available was a specific content type application the end behavior I plus JSON so some of these design influences that I had when I was building connects API it was what's kubernetes kubernetes wasn't something that upholds something specifically from but it has it has a really great HT API that I used as the influence the basis of kind of the thinking that I had with regard to API is in general Django is obviously a big influences I want to make sure that connects API was something that that work really well Jo because that's I think that's really important and Jane Rimmer also was a big influence in the way that that connects API came about because some of the architectural picks that are available the way that it's designed like you know in this case it's a just a copy so is I think a perfect example of that yes as well with the ecosystem because of these applications are changing so drastically with requirements we need to implement I wanted to make sure that this is something that works well for that because that's what Kinect is trying to solve as well so that gives a little more details of the specific API primitives that are available connects API you have the API resource when the resource is the representation of the data to the outside world relationships which link made it together for example an author to a blog post an endpoint set which is a derivative of a Jane Doe view jingo view class different HTTP methods are mapped to different instance methods forming a rest more restful interface so a little more about an API resource in particular a Pentax CPR resource you can think of it as comical jingle form but without any validation this is really important to think about in this lake is do you think well if the data is there that's where we need evaluated because you're dealing with untrusted input it's the way that this is designed is that the API resource is actually completely agnostic to where the data is sourced and then there's ultimately helpers that are used in the endpoints which will go over to here a little bit that links it to link it to the datasets so the reason why this is done this way is for portability so for example that so for example this here doesn't necessarily need to be tied specifically to a data source it's tied to the representation of data which commits which allows us to be portable and then used inside that happen client layer as well and some particular design decisions that were made around this was that you'd be able to encapsulate this in this own project that's separated from the project that actually implements how to get this data and then that can also be used as your client that talks back to your API that keeps it all together nicely the model the model later will implement your validation so in this case we have an author which is just a jingo jango model you would build dissin Jango the validation lives there using genome model validation so all your validation would already be capsulated through your model and then the finnex api will call right into that the model could actually even be a debt doesn't even need to be a django model it could be anything that you can pull data from the data into FedEx API uses relationship relationship information to to serialize leakage so a relationship defines how you link data together we have here the same resource that actually adds in the relationship information here so relationship can either be a non collection which would be a minute to one maybe be many many authors to one publisher or it could be a collection which in this case would be an author has posts and the post is being defined here using so the string values that are there is the first argument are actually the API type that are all being registered as you create your resources through the API dot register and then it's able to kind of fill up this graph and it will know how to serialize it once it comes time to serialize the data an API endpoint set an API endpoint set is kind of what binds the resources to these methods so when you perform a get it's gonna get translated into in the next API into a retrieve method where you would actually implement the logical so here a second an API resource endpoint set is actually derives from the endpoint set itself and that's largely what you use to create the endpoint set that link the the resource to the to the endpoint set all of the URLs are automatically generated and it provides simple validation a simple validation primitive to actually connect the data to the resource and I'll show here this is the first part of it cuz this can get really long your actual resource a little bit of an author in this case so here we actually are importing the the resource we are binding the endpoint set to the to the resource the author resource and this is where you define the kind of the basic bits of the of the author and how it's gonna hook up into your URL so there's a base name which is just largely it's just the singular name of the of the model or whatever the data model is and then the basic reg acts which actually defines kind of where it's going to live in your in your URL namespace but it's not at the collection level and then the look of actually defines how oh look for the individual object that's inside that inside that collection so in this case the field is a PK so you actually kind of think of a URL comma it kind of all just this all kind of gets compiled down into the single reg X which would be authors with the PK be mapped out of it and then these are the methods that you would define in your endpoint set to actually link everything all together so you'd have a list retrieve create update destroy which roughly map into a get on the collection they get on the on the individual endpoint or the individual object a post on the collection and then a put on the individual object and ultimately a delete on the individual object and the validation primitive inside of create and update is through is through the validate method which actually just says on this particular resource class I'm gonna validate this data asses in the resource actually defers it off to whatever the model is and you can actually write whatever validation logic you want in that with statement and it'll handle all the API errors that come right back out of that so for example if the name needed to have the letter A in it or whatever the requirements may be it can raise the validation air in the in the context Angela taken care of turning that into your API airs for you you don't have to write you need that logic at all that didn't the same applies for the other thing there's a lot of other features that are available in the pin ax API that I'm not gonna be able to get into a lot of the details of authentication is one you know are you who you say you are permissions can you access a given resource clues are all built into the independent API that can help those individual methods ensure that the right person is in the person that you can trust is actually accessing them and then the other big bit of the next API that is really helpful is using API blueprint which is actually a specification for writing documentation that's Miss machine readable is automatically generated through all of your endpoint sets and then you can actually define specific customizations to that documentation and what's nice about using leveraging if you have blueprints is that you have the ability to leverage all the tooling that's available and it's ecosystem so one really neat thing is that you can actually write out your connect say if you use it you can write it read guide using Pentax api and then use one of the tooling that enables you to actually generate a client without having to actually write any client code and it can be in any language because they all the tooling in their ecosystem supports about ten different languages and that's it's all available at us at an individual endpoint that you could hook up and that is everything that I have you can actually look at connects api's codes on github you know column slash pin axe slash panic so yeah there's a ton of documentation there that goes a really great detail on how to actually do a lot of the stuff that I've described here with a lot of examples and my website and my Twitter and if you need any help I can either stuff you can check out connexes slack in youtube or even look it up right on the panache project how much you can get there through the get up your elbow if there's any questions we have the user we have time for a few questions I ask you to wait for the microphone so we can pick it up so I'm not completely sure where if this question is valid but I'm wondering how does this complement or differentiate from json-rpc so JSON API versus JSON RPC I haven't seen JSON RPC but in that particular case would be an RPC or a remote procedure call that would be done more about actually serializing the the actual method calls that would translate into something specifically it would already be written in your Python code this is actually kind of providing a layer between how you actually call into into this versus the code to your writing so something that would work really well that would fit inside the Django instead of a jingle project oh hi um so my question is can you provide completed samples or point me to a lane or something the right time really compared peanuts API I can shrink or explain work or provide real real cases going on you when you see Yangon explain why they say it doesn't work for me yeah so our documentation actually has a lot of examples of how you might integrate with with real genome with real Jango models like blog posts and stuff I'm not sure if how I would look compared to Ginga rest frame work but you can see a lot of the things like I need to accomplish this one thing let's say for example I need to expose blog posts you can you could see how that would look and how it all connects and then you can easily hit it using just some curl or whatever to kind of see what it looks like when that data comes back the JSON API the specification their website has a ton of information about exactly the way that data is going to come back and how you how you would expect it and how you might implement a client that actually does interact with that API there's a lot of because it's built off a specification there's a lot of other clients already built that know how to speak that through that specification who's that mister your question briefly they've got a spring we're actually added JSON API support in the last session today 33.4 so that's why I'm asking about the concrete difference yes I was I was here we started this project back in January so at the time there wasn't much other than some for matters that were that were third-party that you can install with Django rest framework that will actually take the already serialize format of Django rest framework and translate that into JSON API so you can use any clients that I already have it whereas though the point of this one was to hopefully get something that was actually native to JSON API was able to take advantage of all of the bits of the specification such as relationships in the compound documents and all that kind of stuff so I'm not sure I've been seeing the stuff that they put into general remark recently so I'd have to look at that like not week oh yeah see this