API First Design and Django

Speaker 1: Welcome on stage, Klaus. And um you're gonna tell us a bit about uh APIs, how to get started with some of the questions that perhaps are not always asked um and how to get a a a good first start on on building an API for your solution. And um thanks for joining us today. Thanks for uh contributing to to the day and um to everyone sitting out there. Please remember to to register and so on so you can ask the questions already now. And we'll be uh I'll be back up here with some questions perhaps. Um yeah, take it away, Klaus.

Speaker 2: Yeah. So yeah, hi everybody. Hi people online. Uh Welcome to this presentation about API first design in Django. I'm Klaus, and besides the German-ish name, I'm actually Brazilian, so never mind my accent. Bear with me. I've been using Django for a long time already. It's been a really lovely journey. And for the past four years, I have been writing APIs, more specifically, REST APIs. And yeah, what's an API again? Just to be sure that we are all on the same page. And APIs can be described as that sort of, or at least

Speaker 2: web APIs can be described as that sort of URLs. that are specialized to accept and return uh raw data or more specialized data. But they are not always the first thing that we think when this amazing uh idea comes, right? Uh sometimes we are we have this amazing Tudelis app that we are trying to build something different that no one tried before. We all we all do that And we don't think about APIs from the first place, right? We usually start by coding. And that's actually an approach called known as code first. That we start by telling Django, right? Uh I mean we are in a Django conference, so yeah, that's that's the way we do.

Speaker 2: And then we start to kiss sketch up some relationships in our database to make sure that our models are going to look pretty. And then we write code and we write it well with test-driven development and even some deals, maybe using this full stack approach of Django that can do some server-side rendering and deliver some HMLs. And eventually some API endpoints as well, because our frontenders they want to make the application a bit more real-time. And then we deal with deployment and CI, CD, monitoring, logging. And then we start to talk about this with other stakeholders. For instance, a front-end guy that's working in your company or a mobile developer that is trying to make this same version, this

Speaker 2: solution work on a mobile environment. And yeah, here is where integration problems can start. And I'm being a bit dramatic here. I would say a lot dramatic here. But it's um a really good example is uh it happened before uh in the companies that I work for And one of the reasons that Django is um Django is nowadays being used to write uh APIs and it's being heavily used to that And there are some explanations to that. One of that is the microservice architecture getting more and more popular. And another one is that the so-called web development, uh the modern web development way We have specialized people

Speaker 2: doing it like frontenders, back-enders, and we have this integration between those two teams or specialties And that's why you would end up writing an API, even though you are using a Django that is a full stack framework that can deliver HML for you. So okay, that's the connection between Django and APIs, but what is API first then And it's uh it's not something new, it's actually it's been discussed in the web development uh web development world for a bit of time. And I mean that's the best explanation I would have. It's like thinking about the API first and designing it first before even coding.

Speaker 2: Again, a bit dramatic, but you we will get there. Still too shallow, too vague. How can we be more accurate about this API first design princip uh idea? And there we go with three principles that at least help me figure out if I'm actually using it or not properly. Again, principles, not rules, so it's not mandatory to follow all of them, but uh I'm sure that they are going to help you out with this idea. And the first one, your API is the first user interface of your application. And that can be mean two things. The first one is that you shouldn't have anything else

Speaker 2: that's not covered by the by an API. And by that I mean you shouldn't have a frontend that doesn't rely on an API that is delivering some sort of use case or flow. that doesn't have an API. Again, a bit strict, a bit dramatic. We don't need to be that strict about it. But it it also means that You are actually bringing all the concerns that you would have with your front-end guy or even with your UX uh professional, the designer or the architect We are thinking about it about it when we are designing the solution and bringing it to the context of building an API instead of an user interface. So in other terms,

Speaker 2: we would say like yeah, we should invest not the same amount of time that we invest building user interfaces, but we should invest some time on building APIs as well. The second one, your API comes first, then the implementation. And this here is to make sure that you are not doing the code first approach. You are trying to be more design-driven here And with that, we can actually uh we have different tools to help us out with that. I'm going to talk about some of them later But the idea is actually like let's let's think about the API and let's let's give it the proper importance and let's care about coding later And number three, your API is described and maybe even self-descriptive.

Speaker 2: And that means that uh that means documentation, and there uh there is no no other way to say that, but Yeah, documentation. We should be caring uh about that. We should be caring about how the developer, the the the guy that's going to use our API uh how can we make him more comfortable about it and provide as much information about it as possible and by self-descriptive Maybe we can add some metadata to our API like we do when we use the only schema hypermedia, for instance. So we are the the API itself is providing some context. So the user can actually navigate through how different endpoints and understand uh some actions that uh he or she can can can do.

Speaker 2: But by the end of the day, it's about caring for other developers and at least for me as a developer, my point of view regarding EPI first is developer experience. And we can summarize it as if you're caring, if you're dealing with developer experience and trying to improve it, you're actually somehow uh uh practicing API first. And uh the one thing that I like about this I this whole idea, this whole concept, is that you can have different points of view here For instance, for an architect, uh it means that we are going to have a platform, a cohesive platform, that's going to provide solutions for different clients and we don't need to repeat ourselves. So we're we 're going to be in a good shape. But for marketing, for instance, and

Speaker 2: sales, it's a different channel of distribution. So we might have some economic impacts by doing that instead of caring or of developing the API afterwards. And well, how can we connect everything with Django? Of course, we are in a Django conference And one of the things that I like most about uh this Python and Django is that you have this dynamic environment that you it's hard to have in different languages and frameworks. So let's get started. The following slides are based on a process suggested by Jennifer Reggins in an article that she wrote for

Speaker 2: Programmable Web. And she she has this really amazing idea about how we should do that in order to make sure that we are following API first principles. So it's an adaptation of that, it's based on that, and it's I think it works really well with Python in Django. So the first step is design the API. Yeah, we are talking about API first, so design the API is possibly the first thing that we should do. And that this day is uh this time uh step, sorry, uh we need to understand the requirements, we need to know the stakeholders. when possible and set some standards. For instance, are we going to be REST, RESTful, JSON API? What are we going to do?

Speaker 2: And they start to define some behaviors that can be uh can be crucial to your business uh doma to your business logic. And this document here, yeah, it can be seen there. This document here is an API API blueprint example. It's a request feature change written with API blueprint. Which is a specification language that works on top of Markdown. So it's relatively easy to write and read. And you can describe how your API is going to behave based on this specification. There are other uh options available like Swagger or RAMO or even OpenAPI specification. That is the most recent version of Swagger

Speaker 2: so far. But you don't need to be that fancy. I mean, you can just sketch up some JSON payloads and you are going to be fine But the thing is you are starting to consider different use cases and flows and discussing it with stakeholders again when possible, if you have a front-end guy in your team Or if you have a provider or or some sort of third department that's going to integrate with you, it would be nice to have them as part of this process as you can And the next step is the validation. It's more, it works like some sort of proof of concept that we do sometimes. uh with um by coding and the idea here is that once you have this idea you should be able to validate it with your stakeholders.

Speaker 2: And by that we can use some mock servers. Pro is one example that based on the specification they wrote before with a formal language You can run a mock server and they can use it. They can integrate the mobile or the web app without any line of code being written in the back-end server But yeah, Django again, Python Django is so dynamic, so lightweight, and it's perfect for prototyping, right? So here is an example of a static view written with Django. that you can just pick some state static data and and stack payload that you you agreed with your peers, with the stakeholders, and pretend that you have a final code written.

Speaker 2: So they can start working on their side and you can start working on your side in parallel and it's I mean it's a perfect word, it's almost autopic, but still it's a good idea to avoid the integration and contract problems that you are going to have by the end of the process if you don't think about them uh as early as possible. And test often often, automate when possible. And there is this tool called Dread. It's a really interesting one. It's a common line tool that you can use, uh Open API specification. uh document or API blueprint document and point it against a service that you have and it's going to validate if that specification that contract that you wrote

Speaker 2: Is still valid. So it's some sort of applic API testing in the pyramid test, but still uh it's a really good one to have in your CI and to make sure that you are not breaking the contract, we are not uh The contract is still valid, so the your clients or customers are still be able to use your API. And finally we can start coding, right? And yeah, pick Django. And if you if you're going to write APIs with Django, I would say go for Django REST framework. Because it's a really cool library that's going to solve a lot of problems for you out of the box. And here we have different uh we have uh four different elements That

Speaker 2: shows how easy it's to build an API Rust framework. We start with our Django model, then we go to a serializer that is a REST framework element that's going to translate requests to model operations and vice versa. And we have the view set that's going to connect everything. It provides us up rate, replace up and delete a set of endpoints And the last part is is like we are connecting it to Django so we can access it through uh the Django router. So it's actually pretty nice. If you haven't tried Django Rust framework before, it's really awesome. Sometimes we will

Speaker 2: uh face this problem of over and under threatching mainly with API uh with REST APIs. And that means that uh overfetching, for instance, is like you all have this endpoint that's providing an amount of data And your client, uh he simply doesn't care about it. Like for instance, a mobile version of your application that doesn't use every single information you have in your endpoint. So how can you avoid this? And as we saw before, it has other impacts like Bangdo if that is being used and shouldn't be, and of and also some ecological impacts as well, as you saw before. So how can we prevent this kind of thing from happening? And Django Rust framework has this uh Add on this plugin I would say called

Speaker 2: Flex Fields, which can allow you to specify which fields you want to be in your payload. In this case I want to beat n I would just want the title, so that's what's going to happen and that's what's uh the endpoint's going to return for me There are some other options. You could write a specific version of your endpoint for your mobile client, for instance, with less information. It's still valid. Or you can consider a different protocol, a different technology that's not REST. And that's okay. API first is not about writing RESTful APIs. API first is about developer experience. And if GraphQL is going to provide your customers a better developer experience than a restful

Speaker 2: set of endpoints Why not? And that might happen, like you might uh conclude that WebSockets is the answer or even GRPC, who knows? So It's not uh uh uh you're going to Google about it and you're going to have to see a lot of articles uh talking about REST APIs in this under this API first uh design umbrella, but it's not about REST at all, it's about the API itself and it's about developer experience. It's official, now it's time to release, and this step here, we are making that agreement, that sort of ideas and proof of concepts, we are turning it into something official And it should happen before, because

Speaker 2: uh if you follow Jennifer Ring 's article again, uh this should be happening after test. But I mean we have some really cool tools in Django in the Django environment, so why not do this here? And with Rust Framework, URI template, and PyYWAMO We can have this really awesome generate schema, a task in your pi in your manage it. py that's going to generate this open API specification document. based on the elements that you already have in your code, the model, the serialized and and the views. So why not, right? And this is useful because this document is readable by humans and by machines as well. So it's easy to share. You can send it to, I don't know, uh, the third party that's going to integrate with you.

Speaker 2: So they It's start they are going to have an idea how your API is going to look like. They can use some uh SDK generators that read this specification and generate, I don't know, Kotlin code based on that. It's still a topic, but yeah, it can work. And we suddenly start to deal uh with changes, right? Uh that happens a lot in a rest frame in a rest environment and a set of In API is using REST, sorry. And Django REST framework they provide this engine for versioning, and you have different options here. You can use the path like slash v1, slash your resource. Or you even use an query string and

Speaker 2: headers, why not? I think GitHub uses headers as well. It's quite neat. Or not, or you don't care about versioning and yeah, you do don't do versioning at all. And my way of thinking here is that uh even though you are you have full control of your server side and client side I think you should start with at least a V1 slash because suddenly your API is going to grow and you're going to break a lot of contracts, so you might need to version you might need to start using version And the red racks are going to be a mess, like red racking for a standard URL that you had before to a version uh URL that you now have. So consider using it uh sooner and consider using it from

Speaker 2: from the start. But still if you have full control of your server and your client, uh I don't think you should care that much about it. It's too much of a of a hustle. And now it's time to release. And here again we are talking about documentation. Uh release is not just about code being production in this context. Release is about any artifact that you are building that are going to turn it easy think turn it easier to the user to use your solution uh they they they are going to be inside this step as well And by documentation with this library that I don't dare trying to say its name because

Speaker 2: yeah my English uh but with this library here you have this uh this visual interface out of the blue. So it's just a matter of installing it, a bit of configuration in Django. Of course if you use Django Rust framework You're going to have it, you can interact with it, uh and see how your model or how your endpoints are going to behave. It's really nice to have it. A lot of uh I don't know about you, but like Looking at Stripe or or even Twilio, they have those developer portals that are really awesome and provide a lot of content, a lot of information that are really useful So you have the opportunity to do that in a sort of automated way.

Speaker 2: And the engagement part, uh one of the last parts here, we are almost there. I rushed a bit, so The engagement part, it's uh again, the we should be investing as much time as we invest in visual interface in our APIs. So the engagement part is the part that you go out there, you start to collect feedbacks and monitor your API and see how you can improve it. TradeShift is a startup here in Copenhagen and they have this developer center. It's really cool. And I worked there for a while. So They have this really interesting concept of building the documentation automatically. So every single release they have it updated.

Speaker 2: And it's really nice. Everything works on top of Swagger files. So machines can integrate. A developer experience experienced team has been formed just to make sure that we are providing they are providing and not working there anymore. But they are providing uh the best experiences possible to developers. And repeat. You don't need to be waterfall about it, you can use every single uh uh agile methodology or or framework you know you don't you can be incremental here And for the readings, uh yeah, it's actually almost we are actually almost there, so uh almost lunchtime I wrote an article about API first

Speaker 2: and which is more based on Jennifer Regan's uh results and and and the research that she has been uh doing about it. It doesn't talk about Python or Django, but still a really good reference if you're going to if you're looking for the reference for this talk, they are there How to design great APIs. This is the article that I've been talking about from Jennifer Reggins. It's really interesting because besides the process that I just kind of showed here She also talks about some economic axioms that you might face with API first. So it's a really interesting article to be aware about.

Speaker 2: And the the book from William Vincent. A lot of ideas for this talk are from this book. So if you are willing to write Django APIs with Django Uh yeah, it's a really nice one. Uh go for it. The API first section here is awesome. Okay, it's been too early, but lunchtime is always uh as every time, so I'll be around if you have any any uh story about documentation APIs and and developer experience. I'll be around and for you people I'll be on Zilli. Thank you.

Speaker 1: Super cool. Thank you so much Klaus. Um I'm just waiting to see if there's any questions that are gonna hop in from the internet. Um meanwhile I have a question, perhaps related to the talk coming up later about documentation um and and these APIs. Code first or perhaps documentation first. I know there is a lot of automated framework type so building your documentation directly out of your API. Is is that a way to to frame it? Uh can we build our documentation of the API before as a kind of uh design?

Speaker 2: Yeah. Yeah, we can. Um if I mean We can start by if we consider the API as something apart from the implementation , we have to give it some meaning, and by some meaning we will probably start writing uh specifications that can be attached to the any kind of we have a lot of uh tools out there that generate implementation, validate if the contract is right or wrong, and even generates code based on uh swagger files for instance. So having this kind of uh having this kind of approach writing caring for writing the specification for us and then starting implement it, it can provide you

Speaker 2: this kind of benefit. You can attach uh you can automate a lot of different aspects documentation is one of them and generate uh developer portals as we see we saw here and swagger the swagger environment they have a lot of tools regarding this and they have even uh web apps that do that. You don't even need to have uh CI instance that point to somewhere to just upload a standard file and they will build this uh documentation for you But we the proposal here, the the process that I showed, we mix, right? Because we don't actually just write implementation and then uh about the code. We are kind of mixing because Django, if Django Rep, they have these sort of tools that will

Speaker 2: allow you to provide it based on the elements that you already have. And that's one of the things that API first can be a burden because if we are writing uh specification first and then the code, we might have some sort of duplication in some way So if this is clear, you are going to rely, ev everything is going to be around the models, the views, and the spare life, but you are writing and they are already uh Uh we are putting a lot of work on that, describing them a lot, so why not just use them and program generate the the patient based on those elements

Speaker 1: I can't wait to get started and and try out this new approach. It's a new uh also perhaps for me a new way of thinking uh where I want to start building a solution. Um I think people are perhaps thinking a lot about lunch. We need to refuel a little bit. But uh a couple of uh firstly um we're both wearing almost the same t-shirt, but yours is unique. That's one of the perks of uh being a speaker here. Um if you're interested in this latest Django design, which is uh made by Sarah who's uh also drawing sketch notes for the talks right now, uh

Speaker 1: you're welcome to Send us a message on on Zulib. This is special production, so we don't wanna uh we don't wanna invest in anything that there's no demand for, but please just reach out to us And we have a a sort of book grafo open on Zulip. Um there is a public uh publisher called Manning publications that are writing books about Python and uh they're revave five books and uh if you want to join the REFO you add your name to the topic, I think add it in the Django Day channel. And there's also a code for having discounts there.

Speaker 1: Um we're gonna have a a lunch break now. And um for those of you at the venue, that means that the lunch will be outside. Um and uh that's the next meal, but perhaps you are a very organized person and you're also thinking uh one more meal ahead. Um I'm gonna be um out in the rain picking up some coupons for ordering at another place and I'm gonna bring them back during the lunch break here. And I'll explain that to you when we resume how that works. And I think thank you once again, Klaus , so much for this. And

Speaker 1: yep, see you all. Um let me just see what time are we coming back. We are coming back at quarter past one. See you then