On Tue, Jul 6, 2021 at 1:56 PM Jose Salvatierra ***@***.***> wrote: *Note*: this is a long post, I've been thinking about the stuff here for years. I'd love to hear your thoughts, opinions, and feedback! ------------------------------ A few years ago we wrote and recorded one of our most popular courses: “REST APIs with Flask and Python”. With it, we’ve helped tens of thousands of students get started with backend development with Flask. However, in these few short years, three very important things have happened: 1. Technologies have evolved. Flask reached v1 and then v2, some extensions have become deprecated, and other extensions have been created. 2. We’ve received hundreds of pieces of feedback, including application feedback and suggestions for new content. 3. Our course-making abilities have improved. We’ve made a number of other courses since this one was produced, and we feel like now we can do a better job! In this discussion piece, I’ll outline what we’ve decided to change in the second version of the course (I’ll call this v2 from now). I’ll also mention some things that we’re still deciding and that we’d like your input on. Finally, I’ve also got some practical house-keeping updates that will improve the course-taking experience in v2. New updates in v2 Updating Flask to v2 One of the main things that prompted a complete re-record of this course was that Flask reached a stable version in 2018. At that point, not much had changed. But since then, Flask has seen a more intense update cadence, recently reaching v2. Although not much has changed in terms of what the course covers, there are small differences. One of the main ones are some new async functionality, which we will cover and compare with other libraries such as FastAPI, Sanic, and aiohttp. Another change is the shortcuts for route definitions. Now, instead of this: @app.route("/form", methods=["POST"]) def submit_form(): pass We can write this: @app.post("/form") def submit_form(): pass There are other updates to Flask which we will try to include in the, including: - Multiple changes to send_file for file downloads. - Nesting blueprints. - Using the flask executable instead of running through the python command using a run.py file. More database relationships and API implementation In v1 of the course, we built a REST API project that mimics a supermarket backend: there are users, stores, and items. There was a database relationship between stores and items (one-to-many). Many students rightly mentioned that many-to-many relationships were not covered in the course. That was because the course was already getting quite long, at 17 hours. However, almost every application will use them, so we will include them in v2. Deployments to AWS instead of DigitalOcean In v1 of the course, I opted to go with DigitalOcean instead of AWS or Google Cloud because of two main reasons: it was easier (for students and for myself), and I’m not a big fan of either Amazon or Google—they both have way too much power in terms of their hosting market shares. Things haven’t changed at all since then. In fact, they’ve gotten worse. But maybe because of that, developers just *have* to know about AWS. We can't justify teaching about backend development without including AWS. That’s why, even though I do this through gritted teeth, we’ll be covering AWS in the course instead of DigitalOcean. We’ll use EC2 for server provisioning and RDS for databases. We're still considering covering file storage in the course. If we did, we would use S3 for that. We’ll also cover Heroku for those of you that have enough money and not enough time to worry about deployments. Heroku is definitely much more expensive, but it’s also much easier. Also, the Heroku free tier is good for students who want to showcase their projects but don’t have any production load. Greater focus on API design and documentation When you’re developing a REST API, some of the most important questions are: - What is this going to be used for? - Who is going to be making requests to it? - What are some technical and non-technical requirements? That’s something that we want to cover in more detail: planning and implementing a REST API based on real-world use, rather than just as a project that has been planned for you. In v1 of the course, we used Postman to create collections of requests to the API, and then we wrote documentation on those requests. This is simpler than writing documentation by hand, but lately I’ve been feeling that it’s a bit limiting. So in v2, we’ll give a bit more focus to writing the documentation manually, as well as integrating Swagger into the API that we develop. Password encryption There is something that you just can’t not do: encrypt user passwords. In v1, we didn’t encrypt passwords (although we did write multiple guides on the subject and linked them in multiple places of the course). In v2, we will make sure we never even leave the door open to not encrypting passwords. Writing tests with Python and less reliance on third-party tools Postman is great and makes our life much easier. It helps organise our manual testing, and its automated testing functionality can be really helpful. If we teach students to only write tests using Postman, especially if that’s the first kind of test they write, they may always lean on that in the future even when a different kind of testing would be more appropriate. We feel that writing automated tests alongside your code, without reliance on third-party tools, is more reflecting of what happens in the real world. That’s why in v2 we will cover writing automated tests using Python instead. We will still use third-party tools to do manual testing, as anything else would be borderline masochistic. However, we will try to avoid depending on any particular feature of the third-party tool. That’s why we’ll be using both Postman and Insomnia REST Client when developing the course, and make sure that everything we do can be done with both. Changes we’re still thinking about Flask extensions for REST API development Flask-RESTful is one of the simplest extensions for REST API development with Flask we’ve found. At its core, it lets us easily map classes and their methods to API endpoints: class ItemResource(Resource): def get(self): return {"message": "An item."} That, with some more code to register the class with the Flask-RESTful extension, can give us an endpoint like /item. When accessed with a GET request, it’ll give us a JSON representation of the dictionary it returns. It adds a bit of abstraction on top of Flask, which I find helps with speed of development. That’s really everything it does! So although it hasn't received meaningful updates in a long time, I'm not sure it really needs them. It does make you wonder though, if there isn’t another extension that can be just as simple, but also give you more as your application grows. We’re looking through community extensions, such as Flask-RESTX, to try to find something better. Flask-RESTX is a little bit more complicated, but it exposes that complexity incrementally. As far as we can tell—before having researched this in depth—using Flask-RESTX can be just as straightforward as using Flask-RESTful, but it can also do more if you want it to. Added functionality includes: - Integration with marshmallow for loading and dumping, which also makes it easier to define what arguments an endpoint should receive. - Integration with Swagger without much boilerplate, as a lot is inferred from the code. - Documentation which describes a lot of what you can do, so there’s potential for students to learn more about this library. For these reasons we’re considering using Flask-RESTX instead of Flask-RESTful. If you know of any other libraries which are still being maintained, and aren’t overly complicated or prescriptive in how code should be written, please let us know below! Docker Docker--and containerization as a whole--is another technology that has taken over the world by storm. Containers help with running applications in the same environment no matter which stage of deployment they're at. They also simplify the deployment process once it's been set up. We haven't covered Docker before because there is a lot to know about it, and we wanted to keep the course focused on REST APIs with Flask and Python. We felt that explaining Docker to beginners in this course would split the focus and require a lot of time. We've thought about a few options, but none of them satisfy us fully: - Don't cover Docker at all. - Cover Docker fully, from zero knowledge, to deployment. - Assume the student knows a bit about Docker (or has other ways or learning about it), and just cover the deployment of Flask apps using Docker. The last option is the most appealing, because it allows students to learn about Docker with another guide or course, but still includes how to use Docker for our purposes. What do you think? Would something like that be sufficient for a REST API course, in your opinion? Have you got any thought about this? Celery Celery is a great technology for offloading work to another Python process so we can keep the API running while something's happening in the background. Also, it has scheduling abilities so we can run functions periodically instead of relying on cron jobs or background threads. It's something that many students have asked for, and initially we thought about creating a completely separate course just for Celery. However, even lately on our internal Teclado projects, we've felt the need of relying on Celery or similar background scheduling technologies. REST APIs and Celery are a great match, so we're open to at least covering some practical uses of Celery in this course. Again, if you have any thoughts or opinions on this, we'd love to hear them. Other topics Are there any other topics, libraries, technologies, or anything else that you'd like to see in this updated REST API course? (please, don't say Django). We're all ears! Also, if you have any material (code, guides, articles, tutorials) on the matter, share them with us! And if you want to write some, get in touch. We'd love your contributions. Changes to the structure of the course and this repository The last thing to talk about is the course-taking experience. Over the last few years we’ve gone from making courses purely on video to including more and more text-based content. There are two main reasons for this: it’s much easier to keep up to date, and it’s much easier for students to scan it, copy from it, save it, or otherwise reference it in the future. Video-based courses are (I would say) much better for the first time you go through them, especially for students with less experience. But when you want to go back to something you watched months ago, text makes it much easier. That’s why in our latest courses we’ve tried to include both video and text. This course will be no different. Every video lecture will have a page in our e-book with either a transcript or at least some notes and the code that was written in that lecture. We’re hoping that when we find small errata or new small updates appear, we can make them to the text content while making small changes to the videos. When there are larger updates, we can re-record the videos then. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#32>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADKS4RBIZ3RMFJMVC4YPUYDTWLOPVANCNFSM474KMPDQ> .