By now you should know already what a REST api is, if you don't I recommend you read about it here.
As a very brief summary, building an API in a RESTful way means that you have to build your URL endpoints grouped by "resources". A resource is something you want to manage, e.g: Student, User, Car, etc. A resource is something similar to a database table but we call them "resources" because of a few exceptions.
Here is an example of RESTful API endpoints to manage Students:
|GET||/student||Should return all the students|
|GET||/student/1||Should return a single student with the id=1|
|GET||/cohort/1/students||Should return all the students from the cohort with id=1|
|POST||/student||Should create a new student|
|PUT||/student/1||Should update the information of the student with the id=1|
|DELETE||/student/1||Should delete the student with id=1|
Take a look at the URL's they follow a pattern, after a while the endpoints will speak for themselves, it will make sense and you will be able to guess what they do or even guess some endpoints. That is the whole idea.
Flask is amazing! It is very similar to Node.js Express Server and that makes it even cooler because you will be able to work with both technologies without much of a learning curve.
Flask is a library for creating web servers and API's, basically when you run a python script that contains the following lines, the computer will start listening for HTTP requests:
In Flask we can add new endpoints by using the
@app.route decorator, don't worry if this is the first time you see a decorator, the concept is very simple and here is a 5 min video explaining it.
If you want to add another endpoint to your API that runs when a client calls
GET /person you will have to add another block of code like this:
If you want your endpoint to answer to POST, PUT or DELETE you can specify that on the decorator like this:
The response can basically be whatever you want as long as it is a string: HTML, JSON, CSS, Images, etc. Just make sure you convert into a string whatever you want to respond.
In the following example we are using the jsonify method to convert a dictionary called
person1 into a JSON string before returning it to the client.
The response code is 200 by default, and 500 if there is an unknown error. If you want to respond to the client with a different code you will have to specify it like this:
Another way of changing the response code using a comma
But what if the request comes with errors? For example: If we have an endpoint to create a person and must specify the first_name AND the last_name but only the first_name was found on the request, this is how we would validate it:
There are differrent ways to integrate Flask to a database server but we will be explaining the integration with SQL ALchemy.
To integrate with SQLAlchemy all you have to do is install the package and import it into your files like this:
Once it is imported, you can start declaring your database models like this:
You can add as many models as you like.
We have prepared this live coding example that you can run yourself in Gitpod and use it as a base for your project.
Flask Rest Hello: https://github.com/4GeeksAcademy/flask-rest-hello