DEV Community: Xulin Zhou

Building a Realworld blog backend in 600 lines of Python

Xulin Zhou — Wed, 12 Feb 2025 14:21:41 +0000

0. Intro

I recently discovered the Realworld DEMO project while wandering through github, it's a spec of a fullstack application DEMO: To implement a medium-like UGC blog site, with implementations of different languages and frameworks, providing:

User registration, login, get and update info, follow, unfollow.
Article creation, update, like, recommend and comment

So I use UtilMeta framework to implemented all the features in realworld spec, and found out it used just 600 lines of Python code, which is more concise and efficient than most backend implementations

UtilMeta Framework is an open source Python backend framework that can develope RESTful APIs more efficiently, support adaptation to mainstream Python frameworks such as Django, Flask and FastAPI.

In this post, I will take you through the complete backend implementation process of the Realworld blog project, from data modeling, JWT authentication, API development and management. I will also attach the complete Python project source code at the end.

1. Create project

Install dependencies

Before creating the project, install the dependent libraries required for this post

pip install utilmeta starlette django databases[aiosqlite]

In addition to UtilMeta framework, we will also use these tech stack in our realworld project:

Develop asynchronous API using starlette (backend of FastAPI) as the HTTP backend
Using Django as a data models
Use SQLite as the database
User authentication using JWT

setup command

Create a new UtilMeta project using the following command

meta setup utilmeta-realworld-blog --temp=full

Then follow the prompts or skip, and enter starlette when prompted to select backend

Choose the http backend of your project 
 - django (default)
 - flask
 - fastapi
 - starlette
 - sanic
 - tornado
>>> starlette

The blog project contains various APIs and models, to organize them in a better way, we use --temp=full in our setup command to create a full template project

We can see that the project structure created by this command is as follows

/config
    conf.py
    env.py
    service.py
/domain
/service
    api.py
main.py
meta.ini

The recommended corresponding usage are:

config: Store configuration files, environment variables, service running parameters, etc.
domain: Store domain applications (django apps), models, and RESTful APIs.
service: Integrate internal APIs and external services
main.py: The entry file to run, which can be used python main.py to run the service directly during debugging.
meta.ini: Declare metadata, and determines the root directory of the project for meta command

2. Write the data model

For an API system like blog, which focuses on the data CRUD, we often start to develop from the data models. In the API Specs, we can conclude that we need to write user, article, comment and other models.

Create an application

Since we use Django as the ORM implementation, we organize our project the way Django organizes apps, and we can simply divide the blog project into two domain applications: user and article.

First add a user application named user to the project using the following command

meta add user

After running the command, you can see that a new folder has been created under the folder domain, with the following structure

/domain
    /user
        /migrations
        api.py
        models.py
        schema.py

The user models for the blog and the related APIs for user and authentication will be placed in this folder

It's ok if you are not familiar with Django apps usage, you can understand it as a organize approach to split code for different domains,

Let’s add an article app called article. which will place article and comment models and APIs.

meta add article

User model

We will write the data model as described for the user data structure in API Documentation: User . We open domain/user/models.py and write the user’s model.

from django.db import models
from utilmeta.core.orm.backends.django.models import PasswordField, AwaitableModel

class User(AwaitableModel):
    username = models.CharField(max_length=40, unique=True)
    password = PasswordField(max_length=100)
    email = models.EmailField(max_length=60, unique=True)
    token = models.TextField(default='')
    bio = models.TextField(default='')
    image = models.URLField(default='')

AwaitableModel is a model base class in UtilMeta to provide fully async query in Django using encode/databases, which will unleash the async performance for Django ORM

Article & Comment Model

We follow the API Documentation: Article to write article and comment models, open domain/article/models.py and write.

from django.db import models
from utilmeta.core.orm.backends.django import models as amodels

class BaseContent(amodels.AwaitableModel):
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    author_id: int

    class Meta:
        abstract = True

class Tag(amodels.AwaitableModel):
    name = models.CharField(max_length=255)
    slug = models.SlugField(db_index=True, unique=True)
    created_at = models.DateTimeField(auto_now_add=True)

class Article(BaseContent):
    slug = models.SlugField(db_index=True, max_length=255, unique=True)
    title = models.CharField(db_index=True, max_length=255)
    description = models.TextField()
    author = models.ForeignKey(
        'user.User', on_delete=models.CASCADE, related_name='articles')
    tags = models.ManyToManyField(Tag, related_name='articles')

class Comment(BaseContent):
    article = models.ForeignKey(
        Article, related_name='comments', on_delete=models.CASCADE)
    author = models.ForeignKey(
        'user.User', on_delete=models.CASCADE, related_name='comments')

You can find similiar fields in Article and Comment data structure, so we can use model inheritance in Django to reduce the redundant fields declaration

Add m2m model

The blog project needs to record the following relationship between users and the liking relationship between users and articles, so we need to add Favorite and Follow intermediate table model to record the relationship between users, and articles.

We open domain/user/models.py again, create the relational table and add a many-to-many relational field to the User table

from django.db import models
from utilmeta.core.orm.backends.django.models import PasswordField, AwaitableModel, ACASCADE

class User(AwaitableModel):
    username = models.CharField(max_length=40, unique=True)
    password = PasswordField(max_length=100)
    email = models.EmailField(max_length=60, unique=True)
    token = models.TextField(default='')
    bio = models.TextField(default='')
    image = models.URLField(default='')

    # new +++
    followers = models.ManyToManyField(
        'self', related_name='followed_bys', through='Follow', 
        through_fields=('following', 'follower'),
        symmetrical=False
    )
    favorites = models.ManyToManyField(
        'article.Article', through='Favorite', related_name='favorited_bys')

class Favorite(AwaitableModel):
    user = models.ForeignKey(User, related_name='article_favorites', on_delete=ACASCADE)
    article = models.ForeignKey(
        'article.Article', related_name='user_favorites', on_delete=ACASCADE)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        unique_together = ('user', 'article')

class Follow(AwaitableModel):
    following = models.ForeignKey(
        User, related_name='user_followers', on_delete=ACASCADE)
    follower = models.ForeignKey(
        User, related_name='user_followings', on_delete=ACASCADE)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        unique_together = ('following', 'follower')

We have added two new models.

Favorite: the like relation model between user and article.
Follow: the follow relation model between users

We add many-to-many relationship fields followers and favorites to the User model, which will be used in the query APIs

ACASCADE in the example is a asynchronous CASCADE function for Django

Migrate to database

After writing the data model, we can use the migration command provided by Django to easily create the corresponding data table. Since we are using SQLite, we do not need to install the database software in advance. We only need to run the following two commands in the project directory to complete the creation of the database.

meta makemigrations
meta migrate

When you see the following output, you have created the database successfully

Operations to perform:
  Apply all migrations: article, contenttypes, user
Running migrations:
  Applying article.0001_initial... OK
  Applying user.0001_initial... OK
  Applying article.0002_initial... OK
  Applying contenttypes.0001_initial... OK
  Applying contenttypes.0002_remove_content_type_name... OK

!!! tip "Database Migration Commands"
The above commands is Django migration commands, makemigrations will save the migrations in the models to files, while migrate applies all the unapplied migration files to SQLs that create or alters tables

After completing the above command, you will see the SQLite database named db just created in the project folder. If you want to know how the database is configured, please open config/conf.py. You will find the following code in it

service.use(DatabaseConnections({
    'default': Database(
        name='db',
        engine='sqlite3',
    )
}))

This code is used to config the database connections

3. User APIs and Authentication

The Realworld blog project needs to use JWT as request authentication, handling user login and identifying the user of the current request.

JWT authentication

The built-in authentication component of UtilMeta already has the implementation of JWT authentication. We only need to declare the corresponding parameters to obtain the JWT authentication capability. We create a file named auth.py in the config folder and write the configuration related to authentication.

from .env import env
from utilmeta.core import api, auth
from utilmeta.core.auth import jwt
from utilmeta.core.request import var
from domain.user.models import User

class API(api.API):
    user_config = auth.User(
        User,
        authentication=jwt.JsonWebToken(
            secret_key=env.JWT_SECRET_KEY,
            user_token_field=User.token
        ),
        login_fields=User.email,
        password_field=User.password,
    )

    async def get_user(self) -> User:
        return await self.user_config.getter(self.request)

    async def get_user_id(self) -> int:
        return await var.user_id.get(self.request)

We create a new API base class to declare the configuration related to authentication, so that the API classes that need authentication can directly inherit the new API base class., so that the endpoint functions can use await self.get_user() to get the current request user.

For any API that requires a user login to access, you can declare user: User = API.user_config in the parameters, so that you can get the instance of the current requesting user directly by user.

For more about user authentication, you can refer to UtilMeta Request Authentication

Environment variables

You should not hard-coded secret keys like JWT_SECRET_KEY into the code, but defined using environment variables. UtilMeta provides a set of environment variable declaration class that we can open config/env.py and write.

from utilmeta.conf import Env

class ServiceEnvironment(Env):
    PRODUCTION: bool = False
    JWT_SECRET_KEY: str = ''
    DJANGO_SECRET_KEY: str = ''

env = ServiceEnvironment(sys_env='CONDUIT_')

In this way, we can define the key of JWT in the variable of the CONDUIT_JWT_SECRET_KEY runtime environment and use env.JWT_SECRET_KEY to access.

User API

For users, we need to implement the user’s signup, login, query and update the current user data APIs：

GET /api/user：Get user info of the current request,
PUT /api/user：Update user info of the current request,
POST /api/users：User Registration,
POST /api/users/login：User login

Before writing APIs, we firstly define the data schemas used by the user APIs, let's open domain/user/schema.py and write:

from utilmeta.core import orm
from .models import User, Follow
from utilmeta.core.orm.backends.django import expressions as exp
from utype.types import EmailStr

class UsernameMixin(orm.Schema[User]):
    username: str = orm.Field(regex='[A-Za-z0-9][A-Za-z0-9_]{2,18}[A-Za-z0-9]')

class UserBase(UsernameMixin):
    bio: str
    image: str

class UserLogin(orm.Schema[User]):
    email: str
    password: str

class UserRegister(UserLogin, UsernameMixin): pass

class UserSchema(UserBase):
    id: int = orm.Field(no_input=True)
    email: EmailStr
    password: str = orm.Field(mode='wa')
    token: str = orm.Field(mode='r')

Now we can open domain/user/api.py and write the user APIs:

from utilmeta.core import response, request, api, orm
from config.auth import API
from .schema import UserSchema

class UserResponse(response.Response):
    result_key = 'user'
    result: UserSchema

class UserAPI(API):
    response = UserResponse

    # GET /api/user
    async def get(self):
        user_id = await self.get_user_id()
        if not user_id:
            raise exceptions.Unauthorized('authentication required')
        return await UserSchema.ainit(user_id)

    # PUT /api/user
    async def put(self, user: UserSchema[orm.WP] = request.BodyParam):
        user.id = await self.get_user_id()
        await user.asave()
        return await self.get()

class AuthenticationAPI(API):
    response = UserResponse

    # POST /api/users
    async def post(self, user: UserRegister = request.BodyParam):
        if await User.objects.filter(username=user.username).aexists():
            raise exceptions.BadRequest(f'duplicate username: {repr(user.username)}')
        if await User.objects.filter(email=user.email).aexists():
            raise exceptions.BadRequest(f'duplicate email: {repr(user.username)}')
        await user.asave()
        await self.user_config.login_user(
            request=self.request,
            user=user.get_instance(),
        )
        return await UserSchema.ainit(user.pk)

    # POST /api/users/login
    @api.post
    async def login(self, user: UserLogin = request.BodyParam):
        user_inst = await self.user_config.login(
            self.request, ident=user.email, password=user.password)
        if not user_inst:
            raise exceptions.PermissionDenied('email or password wrong')
        return await UserSchema.ainit(user_inst)

The AuthenticationAPI iherits from the API class defined in config/auth.py. In the user-signup post endpoint, After the user is registered, we directly login the user to the current request using alogin_user method
(that is, generate the corresponding JWT Token and then update the user token’s field).

In addition, according to the requirement of the request and response body structure in API Specs, we declare that the request body parameter using request.BodyParam, so that the parameter name user will be used as the corresponding key. Our response also uses the template key specified 'user' as the result in result_key of the response template, so the structure of the request and response of the user interface is consistent with the documentm, like

{
  "user": {
    "email": "jake@jake.jake",
    "token": "jwt.token.here",
    "username": "jake",
    "bio": "I work at statefarm",
    "image": null
  }
}

Profile API

According to API Specs, the Realworld blog project also needs to develop a Profile API to get user details, follow and unfollow

Profile API needs a following field that return whether the current request user has followed the target user, so let's open domain/user/schema.py and add code to implement this feature:

# +++ new
class ProfileSchema(UserBase):
    following: bool = False

    @classmethod
    def get_runtime(cls, user):
        if not user:
            return cls

        class ProfileRuntimeSchema(cls):
            following: bool = orm.Field(
                exp.Exists(
                    Follow.objects.filter(
                    following=exp.OuterRef('pk'), follower=user)
                )
            )

        return ProfileRuntimeSchema

and the open domain/user/api.py to write the Profile API

# +++ new
from .schema import ProfileSchema
from .models import Follow

class ProfileResponse(response.Response):
    result_key = 'profile'
    result: ProfileSchema

@api.route('profiles/{username}')
class ProfileAPI(API):
    username: str = request.PathParam(regex='[A-Za-z0-9_]{1,60}') 
    response = ProfileResponse

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.profile: Optional[User] = None

    @api.get
    async def get(self, user: Optional[User] = API.user_config):
        return await ProfileSchema.get_runtime(user).ainit(self.profile)

    @api.post
    async def follow(self, user: User = API.user_config):
        await Follow.objects.aget_or_create(following=self.profile, follower=user)
        return await self.get(user)

    @api.delete(follow)
    async def unfollow(self, user: User = API.user_config):
        await Follow.objects.filter(following=self.profile, follower=user).adelete()
        return await self.get(user)

    @api.before('*')
    async def handle_profile(self):
        profile = await User.objects.filter(username=self.username).afirst()
        if not profile:
            raise exceptions.NotFound(f'profile({repr(self.username)}) not found')
        self.profile = profile

In domain/user/api.py, the ProfileAPI reuses the path parameter username in API class. And the handle_profile before hook queried the corresponding user instance and assigned to self.profile,
so in the API functions get, follow, unfollow, you can use self.profile to get the target user instance, In addition, follow and unfollow reused the serialization logic of the get API by calling it directly.

Hooks in UtilMeta API classes are called before/after the target endpoints or handle the errors. to reuse the logics better, you can refer to Hooks Mechanism in UtilMeta API class

In domain/user/schema.py, ProfileSchema defined a dynamic query function get_runtime, pass in the user of the current request, generate the corresponding query expression according to the requesting user, and then return a new class

In the get endpoint of the ProfileAPI, you can see how the dynamic query function is called

class ProfileAPI(API):
    @api.get
    async def get(self, user: Optional[User] = API.user_config):
        return await ProfileSchema.get_runtime(user).ainit(self.profile)

4. Article & Comment APIs

Next, we will develop interfaces related to articles and comments to implement a series of functions such as recommending, querying, creating, updating, commenting, liking, etc. for articles

Article API structure

Based on API Documentation | Article API , we can develop the basic structure of the APIs at the begining

from utilmeta.core import api, request, orm, response
from config.auth import API
from typing import List, Optional

class ArticleSchema(orm.Schema[Article]):
    pass

class MultiArticlesResponse(response.Response):
    result_key = 'articles'
    count_key = 'articlesCount'
    result: List[ArticleSchema]

class SingleArticleResponse(response.Response):
    result_key = 'article'
    result: ArticleSchema

class ArticleAPI(API):
    class BaseArticleQuery(orm.Query[Article]):
        offset: int
        limit: int

    class ListArticleQuery(BaseArticleQuery):
        tag: str
        author: str
        favorited: str

    async def get(self, query: ListArticleQuery) -> MultiArticlesResponse: pass

    @api.get
    async def feed(self, query: BaseArticleQuery) -> MultiArticlesResponse: pass

    @api.get('/{slug}')
    async def get_article(self) -> SingleArticleResponse: pass

    @api.post('/{slug}/favorite')
    async def favorite(
        self, user: User = API.user_config) -> SingleArticleResponse: pass

    @api.delete('/{slug}/favorite')
    async def unfavorite(
        self, user: User = API.user_config) -> SingleArticleResponse: pass

    @api.put('/{slug}')
    async def update_article(self, 
        article: ArticleSchema[orm.WP] = request.BodyParam, 
        user: User = API.user_config) -> SingleArticleResponse: pass

    @api.delete('/{slug}')
    async def delete_article(self, user: User = API.user_config): pass

    async def post(self, 
        article: ArticleSchema[orm.A] = request.BodyParam, 
        user: User = API.user_config) -> SingleArticleResponse: pass

When writing APIs based on the givin specs, you can write the name, input, output of the endpoints first, then filling with the corresponding logics

Write Article Schema

The article API needs to add, delete, update and query around the article data. we can use the ORM Schema query of UtilMeta to complete it easily. You only need to write a simple class to declare the schema you need and use it directly. Let’s take the article as an example. open domain/article/schema.py and write:

from utype.types import *
from utilmeta.core import orm
from .models import Article
from domain.user.schema import ProfileSchema
from django.db import models

class ArticleSchema(orm.Schema[Article]):
    id: int = orm.Field(no_input=True)
    body: str
    created_at: datetime
    updated_at: datetime
    author: ProfileSchema
    author_id: int = orm.Field(mode='a', no_input=True)

    slug: str = orm.Field(no_input='aw', default=None, defer_default=True)
    title: str = orm.Field(default='', defer_default=True)
    description: str = orm.Field(default='', defer_default=True)
    tag_list: List[str] = orm.Field(
        'tags.name', alias='tagList',
        mode='rwa', no_output='aw', default_factory=list
    )
    favorites_count: int = orm.Field(
        models.Count('favorited_bys'),
        alias='favoritesCount'
    )

In the Schema class we wrote, there are many kinds of fields, and we will explain them one by one.

author: Relational object, it is a foreign key field, and uses a type annotation to specify another Schema class. When querying, author will query out the data of the author user of the article with the fields in ProfileSchema.

All related fields (ForeignKey, M2M, ...) supports query relational object, for example, the author field in the example has a reverse relation articles, so you can query all articles of a user using articles: List[ArticleSchema] in the user's Schema

tag_list：Multi-level relation field，Sometimes you just need to query a single field in a relational table, This field declares orm.Field('tags.name'), so it will query along the path of tags and name. The final query is the name list of the tag corresponding to the article.
favorites_count: Query expression field: You have declared favorites = models.ManyToManyField('article.Article', related_name='favorited_bys') in the User model, so, favorites_count using models.Count('favorited_bys') to query "number of users who liked the article".

Also for the tag_list and favorites_count fields, we use alias parameters to give them real names for input and output (camelCase styled naming according to API specs).

Field Mode

You can see that in the above example, many fields specified mode, this parameter can be used to declare the applicable mode (scenario) of a field, so that it can show different behaviors in different scenarios. The commonly used scenarios in the data CRUD are

'r': Read/Retrieve: returned as the result of a database query
'w': Write/Update: Update existing record in the database using requested data
'a': Add/Create: Add new record to database using requested data.

You can combine mode chars to indicate that a field supports multiple modes. By default, UtilMeta will automatically assign a pattern based on the model field.

Even if you didn't specify mode, UtilMeta will assign mode based on the features of the model fields, for instance, field like created_at with auto_now_add cannot be updated or provided in creation, so its mode will be assigned to 'r', you can also specify the mode explicitly to override the default behaviour

For example

author_id: int = orm.Field(mode='a', no_input=True)

field author_id indicate

This field applies only to the mode 'a' (data creation).
No input is required for this field

From the perspective of actual development, the author field of an article should be assigned from current request user, ignoring other values that may be provided by the client, and should not be allowed to be modified. So the field will be assigned before the data is saved, as shown in

class ArticleAPI(API):
    @api.post
    async def post(self, article: ArticleSchema, user: User = API.user_config):
        article.author_id = user.pk
        await article.asave()

no_input=True will ignore the data provided in the Schema initialization (like data from the client), but still allow developer to assign values in the function

Mode generation

You can use YourSchema['<mode>'] to quickly generate Schema classes in sepcific mode. The UtilMeta module orm provides several commonly used modes.

orm.A: This is a 'a' mode that is commonly used for POST methods to create new objects.
orm.W: This is a 'w' mode that is commonly used for PUT methods to update objects.
orm.WP: This is a 'w' mode that ignores the required ( required) attribute. It is often used in the PATCH method to partially update an object.

So you can use ArticleSchema[orm.A] directly to generate the ArticleSchema class in creation mode as the data input annotation for the create article interface.

Of course, if you think the mode way is too complex, you can split the input / output of different endpoints into different Schema

Dynamic query field

In a blog project, we need to return the "whether the current user likes it" field for each article, and we can still use the runtime Schema function method to handle such dynamic queries.

class ArticleSchema(orm.Schema[Article]):
    ...
    favorited: bool = False

    @classmethod
    def get_runtime(cls, user_id):
        if not user_id:
            return cls

        class ArticleRuntimeSchema(cls):
            favorited: bool = exp.Exists(
                Favorite.objects.filter(article=exp.OuterRef('pk'), user=user_id)
            )

        return ArticleRuntimeSchema

We write a get_runtime class function that takes the user’s ID as input to generate the corresponding query field, so that we can use ArticleSchema.get_runtime(user_id) to dynamically obtain the Schema class in the API function.

Article Query API

We can article list API as an example of how to write a query API. refer to API docs , fill the following sections in domain/article/api.py:

class MultiArticlesResponse(response.Response):
    result_key = 'articles'
    count_key = 'articlesCount'
    result: List[ArticleSchema]

class ArticleAPI(API):
    # new +++
    class ListArticleQuery(orm.Query[Article]):
        tag: str = orm.Filter('tags.name')
        author: str = orm.Filter('author.username')
        favorited: str = orm.Filter('favorited_bys.username')
        offset: int = orm.Offset(default=0)
        limit: int = orm.Limit(default=20, le=100)

    async def get(self, query: ListArticleQuery) -> MultiArticlesResponse:
        schema = ArticleSchema.get_runtime(
            await self.get_user_id()
        )
        return MultiArticlesResponse(
            result=await schema.aserialize(
                query.get_queryset()
            ),
            count=await query.acount()
        )

Our query API needs to support data filtering through tag, author, favorited, and also needs to support the use offset of, limit to control the number of returns. As you can see, we only need to write a Query schema,

tag: Use orm.Filter('tags.name') as the target field of the specified query. When the query parameters of the request contain tag, the corresponding filter query will be added, the usage of author and favorited is similar
offset: Use orm.Offset to defines a standard begining offset. The default is 0.
limit: Use orm.Limit to defines limit on the number of results returned, 20 by default and 100 by maximum

offset and limit is a pair of common paging parameters in API development, the generated queryset can be expressed as queryset[offset: offset + limit], which means client can query a small slice of the result, and alter the next offset query based on the returning values

orm.Query as the type annotation of API function parameter will parse the querystring of the request by default, and it has several common methods.

get_queryset(): Generate the corresponding queryset according to the query parameters. If you use Django as the ORM library, you will get the Django QuerySet. This query set will apply all the filtering and paging parameters. You can directly use it as the input of the serialization method to get the corresponding data.
count(): Get the total number of queries by ignoring the paging parameters. This method is very useful for paging queries, because the client not only needs to get the data of the current request, but also needs to get the total number of results corresponding to the query, so that the client can correctly display the number of pages for paging, or know whether the query has been completed. The asynchronous implementation of this method is acount

In the get method, we not only call schema.aserialize to serialize the generated target query set, but also call query.acount() to return the total number of articles. Combined with the response body structure defined in MultiArticlesResponse, we can get the following response required by the document

{
    "articles": [],
    "articlesCount": 0
}

Using hooks to reuse logic

Reading the API specs in the article section, we can see that there are many endpoints with repetitive logic, such as

In the Create Article/Update Article endpoints, you need to generate new slug fields for the article based on the title in the request data
To query/update/like/unlike/delete endpoints, you need to query whether the corresponding article exists according to slug the path parameter
To query/update/like/unlike/create endpoints, you need to return the target article object or the newly created article object

For these repeated logics, we can use hook function to reuse, and the example is as follows

class SingleArticleResponse(response.Response):
    result_key = 'article'
    result: ArticleSchema

class ArticleAPI(API):
    @api.get('/{slug}')
    async def get_article(self): pass

    @api.post('/{slug}/favorite')
    async def favorite(self): pass

    @api.delete('/{slug}/favorite')
    async def unfavorite(self): pass

    @api.put('/{slug}')
    async def update_article(self): pass

    @api.delete('/{slug}')
    async def delete_article(self): pass

    async def post(self): pass

    # new ++++
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.tags = []
        self.article: Optional[Article] = None

    @api.before(get_article, favorite, unfavorite, update_article, delete_article)
    async def handle_slug(self, slug: str = request.SlugPathParam):
        article = await Article.objects.filter(slug=slug).afirst()
        if not article:
            raise exceptions.NotFound('article not found')
        self.article = article

    @api.before(post, update_article)
    async def gen_tags(self, article: ArticleSchema[orm.A] = request.BodyParam):
        for name in article.tag_list:
            slug = '-'.join([''.join(filter(str.isalnum, v)) 
                for v in name.split()]).lower()
            tag, created = await Tag.objects.aupdate_or_create(
                slug=slug, defaults=dict(name=name))
            self.tags.append(tag)

    @api.after(get_article, favorite, unfavorite, update_article, post)
    async def handle_response(self) -> SingleArticleResponse:
        if self.tags:
            # create or set tags relation in creation / update
            await self.article.tags.aset(self.tags)
        schema = ArticleSchema.get_runtime(
            await self.get_user_id()
        )
        return SingleArticleResponse(
            await schema.ainit(self.article)
        )

We defined several hook functions in our example.

handle_slug: a before hook defined by @api.before to query the corresponding article and assign a value to self.article using the slug path parameter before the API functions executed. The corresponding API functions can access the target article directly using this instance attribute.
gen_tags: a before hook that called before created or updated. A series of tag instances are generated by parsing the fields tag_list and stored in the self.tags attribute.
handle_response: an after hook defined by @api.after, executed after endpoints that get/update/create a single article object, serialize the self.article instance using dynamic subclasses of ArticleSchema and returned, and if self.tags generated by gen_tags is not empty, it will be assigned to the article tags relation

Comment API

Before developing the comment APIs, let's add the comment Schema in the domain/article/schema.py:

# new +++
class CommentSchema(orm.Schema[Comment]):
    id: int = orm.Field(mode='r')
    article_id: int = orm.Field(mode='a', no_input=True)
    body: str
    created_at: datetime
    updated_at: datetime
    author: ProfileSchema
    author_id: int = orm.Field(mode='a', no_input=True)

From API documentation for the comment APIs, we can see that the comment endpoints are all started with /api/articles/:slug/comments, and the path is located in the subdirectory of the article API, that is to say, the API class of the comment API needs to be mounted on the API class of the article API. We open domain/article/api.py and add the code for the comment API

from utilmeta.core import api, request, orm, response
from config.auth import API
from .models import Article, Comment
from .schema import CommentSchema

# new +++   
@api.route('{slug}/comments')
class CommentAPI(API):
    slug: str = request.SlugPathParam

    class ListResponse(response.Response):
        result_key = 'comments'
        name = 'list'
        result: List[CommentSchema]

    class ObjectResponse(response.Response):
        result_key = 'comment'
        name = 'object'
        result: CommentSchema

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.article: Optional[Article] = None

    async def get(self) -> ListResponse:
        return self.ListResponse(
            await CommentSchema.aserialize(
                Comment.objects.filter(article=self.article)
            )
        )

    async def post(self, comment: CommentSchema[orm.A] = request.BodyParam,
                   user: User = API.user_config) -> ObjectResponse:
        comment.article_id = self.article.pk
        comment.author_id = user.pk
        await comment.asave()
        return self.ObjectResponse(
            await CommentSchema.ainit(comment.pk)
        )

    @api.delete('/{id}')
    async def delete_comment(self, id: int, user: User = API.user_config):
        comment = await Comment.objects.filter(
            id=id,
        ).afirst()
        if not comment:
            raise exceptions.NotFound('comment not found')
        if comment.author_id != user.pk:
            raise exceptions.PermissionDenied('permission denied')
        await comment.adelete()

    @api.before('*')
    async def handle_article_slug(self):
        article = await Article.objects.filter(slug=self.slug).afirst()     
        if not article:
            raise exceptions.NotFound('article not found')
        self.article = article

class ArticleAPI(API):
    # new +++
    comments: CommentAPI

We need the comment API's path to be articles/{slug}/comments, so we use the decorator @api.route('{slug}/comments') on the CommentAPI, so that when we mount the CommentAPI on the ArticleAPI, The path to the ArticleAPI is extended {slug}/comments to become the path of the CommentAPI.

The {slug} path param in the comment APIs identifies the article. We use a before hook named handle_article_slug in the CommentAPI to uniformly query out the corresponding article before the endpoint functions is executed.

In the CommentAPI, every endpoints need to receive {slug} path param, so we can declare this param directly to API class, and use self.slug to access this param, this kind of params is called General Parameters of the API class, will also be integrated to the API docs

You can view the full code of ArticleAPI and CommentAPI at Github

5. Mount API and handle errors

We have written all the APIs, and then we just need to integrate them according to the documentation. We use the API class mounting to assign the path to the written APIs, open service/api.py and update the code of root API.

import utype
from utilmeta.utils import exceptions, Error
from domain.user.api import UserAPI, ProfileAPI, AuthenticationAPI
from domain.article.api import ArticleAPI
from domain.article.models import Tag
from utilmeta.core import api, response
from typing import List

class TagsSchema(utype.Schema):
    tags: List[str]

class ErrorResponse(response.Response):
    message_key = 'msg'
    result_key = 'errors'

@api.CORS(allow_origin='*')
class RootAPI(api.API):
    user: UserAPI
    users: AuthenticationAPI
    profiles: ProfileAPI
    articles: ArticleAPI

    @api.get
    async def tags(self) -> TagsSchema:
        return TagsSchema(
            tags=[name async for name in Tag.objects.values_list('name', flat=True)]
        )

    @api.handle('*', Exception)
    def handle_errors(self, e: Error) -> ErrorResponse:
        detail = None
        exception = e.exception
        if isinstance(exception, exceptions.BadRequest):
            status = 422
            detail = exception.detail
        else:
            status = e.status
        return ErrorResponse(detail, error=e, status=status)

We have write handle_errors as the error handling hook, using @api.handle('*', Exception) to indicates that all errors of all APIs will be handled. According to the requirements of API Documentation | Error Handling, we adjust the response status code of the error type exceptions.BadRequest to 422 (400 by default). And return detailed error information obtained through detail of the Error instance.

For example, when we try to access GET/api/articles?limit=x, the response results will clearly reflect the parameters and reasons for the error.

{
  "errors": {
    "name": "query",
    "field": "Query",
    "origin": {
      "name": "limit",
      "value": "x",
      "field": "Limit",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      },
      "msg": "invalid number: 'x'"
    }
  },
  "msg": "BadRequest: parse item: ['query'] failed: parse item: ['limit'] failed: invalid number: 'x'"
}

In addition, the RootAPI we wrote uses a @api.CORS decorator to specify a cross-source policy for all APIs, and we use allow_origin='*' to allow all front-end origins to be accessed.

Cross domain request (or cross origin request) refers to a request where the source origin (protocol+hostname+port) of the browser is different from the source origin of the backend API. In this case, the browser uses a CORS mechanism to control resource access.
The CORS plugin of UtilMeta automatically processes cross origin requests, including responding to the OPTIONS method and returning the correct Access-Control-Allow-Origin and Access-Control-Allow-Headers response headers based on declaration and configuration

6. Configure and run

Time configuration

Since the output time given in the API documentation is in a format like "2016-02-18T03:22:56.637Z", we open config/conf.py and add the code for the time configuration

from utilmeta import UtilMeta
from config.env import env

def configure(service: UtilMeta):
    from utilmeta.core.server.backends.django import DjangoSettings
    from utilmeta.core.orm import DatabaseConnections, Database
    from utilmeta.conf.time import Time

    service.use(DjangoSettings(
        apps_package='domain',
        secret_key=env.DJANGO_SECRET_KEY
    ))
    service.use(DatabaseConnections({
        'default': Database(
            name='conduit',
            engine='sqlite3',
        )
    }))
    service.use(Time(
        time_zone='UTC',
        use_tz=True,
        datetime_format="%Y-%m-%dT%H:%M:%S.%fZ"
    ))

The Time configuration class configures the timezone, UTC, and output time format used by the API

Environment variables

Remember that we introduced an environment variable called JWT_SECRET_KEY in the JWT authentication section? We need to set it, otherwise the project will not run properly, and we can open config/env.py it to see the environment variables we declared.

from utilmeta.conf import Env

class ServiceEnvironment(Env):
    PRODUCTION: bool = False
    JWT_SECRET_KEY: str = ''
    DJANGO_SECRET_KEY: str = ''

env = ServiceEnvironment(sys_env='CONDUIT_')

Before running, you need to set this key first. such as in Linux system:

export CONDUIT_JWT_SECRET_KEY=<YOUR_KEY>

Run the project

Next we can run the project, and we can see that there is a main.py file in the root directory of the project, with the following code

from config.service import service

service.mount('service.api.RootAPI', route='/api')
app = service.application()

if __name__ == '__main__':
    service.run()

So we just need to execute the following command to run the project

python main.py

Since we are using starlette as the asynchronous runtime implementation, UtilMeta will use uvicorn to run the project. When you see the following output, the project runs successfully.

INFO:     Started server process [26428]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Our service runs on port 8000 of the localhost. This setting can be found and adjusted in config/service.py.

from utilmeta import UtilMeta
from config.conf import configure
from config.env import env
import starlette

service = UtilMeta(
    __name__,
    name='conduit',
    description='Realworld DEMO - conduit',
    backend=starlette,
    production=env.PRODUCTION,
    version=(1, 0, 0),
    port=8080,
    asynchronous=True,
    api='service.api.RootAPI',
    route='/api'
)
configure(service)

If you have multiple services running at the same port, you will see the error message like follows

[Errno 10048] error while attempting to bind on address ('127.0.0.1', 8000): only one usage of e
ach socket address (protocol/network address/port) is normally permitted

But all you need to do is adjust the port number and restart the project

7. Connect and Manage

UtilMeta framework has a built-in Operations module that can easily connect and manage your developed API services, including:

Data CRUD Management
Debug API documentation
Write and execute API unit tests
Server-side real-time requests log query
Real time server performance monitoring

When your blog service is developed and running locally, you can see this output

connect your APIs at https://ops.utilmeta.com/localhost?local_node=http://127.0.0.1:8000/api/ops

You can click the output url to enter UtilMeta Platform and debug your local service.

UtilMeta platform has a public management demo for the realworld project, you can click https://beta.utilmeta.com/realworld to view

Let's take a look at the features provided by the UtilMeta platform.

API

Click the API in the left drawer to enter the API management section of the platform

In the API list on the left, you can search or filter APIs using tags. Click the interface to enter the corresponding interface document. Click the Debug button on the right to enter the debugging mode. You can enter parameters and send a request. The right side will automatically synchronize the curl, python and JavaScript request codes corresponding to the parameters.

Data

Click the API in the left drawer to enter the data management section of the platform

The model (table) list on the left can be searched or filtered using tags. After clicking the model, the table structure and table data will be displayed on the right. You can add multiple field filters in the field query bar above. Each field in the table also supports ascending and descending sorting.

Each data cell in the table can be Left-click or right-click to expand the options menu. you can expand the data that is too large to display completely. Users with permission can also edit or delete the selected data row. Click the + button in the upper right corner to create a new data instance

Below the query table is the table structure document of the model, which will display the name, type, properties (primary key, foreign key, unique, etc.) and validation rule of the model field in detail

Logs

Click the Log in the left drawer to enter the log query section of the platform

Filtering options at the left side include log levels, response status codes, HTTP methods, and API paths, and can be sorted by request time or processing time

Click a single log to expand the log details. The log will record the request and response information, exception call stack and other data in detail.

Building an SEO-friendly responsive i18n website using Vite-SSG + Vuetify3

Xulin Zhou — Sun, 17 Mar 2024 14:05:02 +0000

At the end of 2023, I finally decided to renovate my UtilMeta website. The main reason was that the previous official website was a SPA application made by Vue2, which was not friendly to SEO and social media sharing, a hard issue for the official website aiming to introduce the project.

So after a round of research, I used Vite-SSG + Vue3 + Vuetify3 to refactor my website again. It took me about two weeks. This article records the thinking and summary of the development process. which covers:

Why SPA shouldn't be used to build a project homepage?
What is the structure of the SSG project and how to configure the routing of the page?
How to build a multilingual static site, write multilingual page components, and use lang and hreflang to specify different language versions for the page?
How to use the unhead library to configure different HTML headers for each page to optimize search engine index and social media sharing?
How to use CSS @media rules to handle the first screen loading of responsive pages on different devices?
How to handle the 404 problem gracefully and avoid the impact of soft 404 on SEO?

Why not SPA?

Here we first narrow down the definition, defining official website / homepage as an introductory website with an introduction page, pricing plans, about us, etc., rather than a dynamic product with direct interaction (such as various UGC social media platforms). For dynamic products, it’s okay to use SPA, and if you want to optimize search, you can regularly submit some fixed profile pages or article pages to the search engine.

So that’s one reason. SEO. It’s a cliche that SPAs generally only generate a single index.html , and crawling any URL on your site will only return the same content, which often does not include the text, keywords and links that will be rendered, which leads to a mess of search engine results. In Twitter, Discord and other social media platforms that directly grab link meta-information (title, description, illustration) and render it, each of your web pages will only present the same information.

For a project that needs to get customers on the Internet, we should not ignore the traffic from search engines, especially international projects. Even if we come to the AIGC era, LLM like ChatGPT still focuses on crawling web pages for training. At this time, if each page of your project can provide clear HTML results that contain enough accurate keywords and information and conform to Web specifications, Your project or document may also be included by AI and integrated into their output, so I think the optimization of web page structure and rendering can be collectively referred to as Agent Optimization, that means, web page optimization for search engines or LLMs is still very important.

What is the appropriate way?

SSR (server-side rendering) or SSG (server-side generation) are suitable approaches for introductory official website development. For static pages that do not require too much rendering logic, SSG is enough. You just need to throw the generated HTML on any page hosting website or CDN to provide direct access. If you like to take control of hosting, you can also make your own server to deploy. I personally use Nginx to deploy the static pages generated by SSG as the source of CDN.

SSG project structure

Compared with the SPA application, the main difference between the SSG project is that the route and the corresponding page template are fixed, and the HTML file of each page will be generated directly in the building phase, instead of generating only one like SPA.

Reflected in the file structure of the Vue project, SPA applications often need a router file to define the routes of the vue-router and the corresponding components. SSG applications, on the other hand, can define the route of each page and the corresponding Vue page component directly in a folder (often named pages).

So the main.js of Vite-SSG project generally looks like this:

import App from './App.vue'
import { ViteSSG } from 'vite-ssg'
import routes from '~pages';
import vuetify from './plugins/vuetify';

export const createApp = ViteSSG(
  App,
  // vue-router options
  {routes, scrollBehavior: () => ({ top: 0 }) },
  // function to have custom setups
  ({ app, router, routes, isClient, initialState }) => {
    // install plugins etc.
    app.use(vuetify)
  },
)

Instead of the Vue default createApp, we use the Vite-SSG defined ViteSSG, and when importing the route, we use the

import routes from '~pages';

In the support of the vite-plugin-pages plugin. You can directly convert the Vue component under a folder into the corresponding page routes, which only need to be configured in vite.config.js.

// Plugins
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import Pages from 'vite-plugin-pages'

export default defineConfig(
  ({command, mode}) => {
    return {
      plugins: [
        Pages({
          extensions: ['vue', 'md'],
        }),
        ...
      ],
      ...
    }
  }
)

Handle multi-language pages

If your official website needs to introduce your project to users from all over the world, multi-language is basically a necessary option. We take supporting Chinese and English as an example, and other language support methods can be analogized.

In the past, my personal method to handle multiple languages was to set the language according to the Geo-IP location, which was not reflected on the URL, and this is actually a Bad Practice. It is completely uncontrollable for what language version of the page users see when they visit (because they may use a proxy). And so does his audience when a user shares a page, and search engines can’t fully crawl all language versions (because Google’s crawlers are mainly in the United States), there is also a Docs of Google stating that it is not recommended to do so.

For SSG page routing, my multilingual implementation practice is to implement one General page component for each page, in which a lang prop is defined, and all the text displayed in the component can select the corresponding language version according to this lang prop. Since the props of the page are directly passed in during SSG construction, HTML page files in different language versions will be generated. A simplified example of the page component is as follows

<script setup>
const props = defineProps({
  lang: {
    type: String,
    default() {
      return 'en'
    }
  },
})

const messages = {
  zh: {
    title: '构建数字世界的基础设施'
  },
  en: {
    title: 'Building the infrastructure of the digital world'
  },
}

const msg = messages[props.lang];
</script>

<template>
  <div>
    {{ msg.title }}
  </div>
</template>

Next, we can build the folder structure of our multilingual page. You can choose to use different languages as different sub-routes, such as

/pages
    /en
        index.vue
    /zh
        index.vue
    /ja
        index.vue
    /..

In this way, visiting /en will enter the English page, and the visit /zh will enter the Chinese page.

Another option is to select a language as the default, such as English, and place its child routes parallel to the other language directories, such as

/pages
    /zh
        index.vue
    /ja
        index.vue
    index.vue     # en

My website utilmeta.com used the second approach because I want to make the domain name of the official website directly accessible and linked and keep it simple, so I plan its routing in this way.

/pages
    /zh
        index.vue ------ Index homepage  (Chinese)
        about.vue ------ About us        (Chinese)
        solutions.vue -- Solutions page  (Chinese)
        py.vue --------- Introduction of UtilMeta framework (Chinese)
    index.vue    ------- Index homepage  (English)
    about.vue ---------- About us        (English)
    solutions.vue ------ Solutions page  (English)
    py.vue ------------- Introduction of UtilMeta framework (English)

By JavaScript convention, index.vue it is treated as a route consistent with its directory, and other names are assigned routes based on the name

The locale page component only needs to set the lang prop of the general page component to the corresponding language code, such as the Chinese version of the “About Us” page /zh/about.vue

<script setup>
import About from "@/views/About.vue";
import AppWrapper from "@/components/AppWrapper.vue";
</script>

<template>
  <AppWrapper lang="zh" route="about">
     <About lang="zh"></About>
  </AppWrapper>
</template>

The @/views/About.vue is the general component of the “About Us” page, which we passed in lang="zh", and AppWrapper is a general page skeleton component I wrote, which contains the top bar, bottom bar, sidebar and other page structures that every page needs.

Language switching

For official websites that support multiple languages, we can add a button that allows users to actively switch languages. Its logic is also very simple. It only needs to display a list of supported languages for users, and then each language button can switch users to the corresponding page route, such as

<template>
    <v-menu open-on-click>
      <template v-slot:activator="{ props }">
        <v-btn v-bind="props">
          <v-icon>mdi-translate</v-icon>
        </v-btn>
      </template>
      <v-list color="primary">
        <v-list-item
          v-for="(l, i) in languages"
          :to="getLanguageRoute(l.value)"
          :active="lang === l.value"
          :key="i"
        >
          <v-list-item-title>{{ l.text }}</v-list-item-title>
        </v-list-item>
      </v-list>
    </v-menu>
</template>

<script setup>
  const props = defineProps({
    lang: {
      type: String,
      default(){
        return 'en'
      }
    },
    route: {
      type: String,
      default(){
        return ''
      }
    }
  });

  const languages = [{
    value: 'en',
    text: 'English'
  }, {
    value: 'zh',
    text: '中文'
  }];

  function getLanguageRoute(l){
    if(l === 'en'){
      return '/' + props.route;
    }
    if(!props.route){
      return `/${l}`
    }
    return `/${l}/` + props.route
  }
</script>

Take the About page above as an example. If the user is currently in the https://utilmeta.com/about route (English) and clicks on the Chinese language, he will be guided to the https://utilmeta.com/zh/about page. From the user’s point of view, the structure of the page is exactly the same, but the language is switched from English to Chinese.

Inject HTML headers into the page

For static pages, the meta information in the header tag <head> are very important, which determines the index and keywords included by search engines, as well as the information rendered by page links when shared on social media. Generally speaking, the page components of Vue are only elements in writing <body>. But just by using a library called unhead, you can write different headers for different pages. For example, the following is the meta information I wrote in the page component of the UtilMeta English homepage.

<script setup>
import { useHead } from '@unhead/vue'

const title = 'UtilMeta | Full-lifecycle DevOps solution for backend APIs'
const description = 'Power the builders with full-lifecycle solution for backend apps and APIs, ' +
  'our products includes UtilMeta Python framework - a progressive meta backend framework, API console and utype'

useHead({
  title: title,
  htmlAttrs: {
    lang: 'en'
  },
  link: [
    {
      hreflang: 'zh',
      rel: 'alternate',
      href: 'https://utilmeta.com/zh'
    }
  ],
  meta: [
    {
      name: 'description',
      content: description,
    },
    {
      property: 'og:title',
      content: title
    },
    {
      property: 'og:image',
      content: 'https://utilmeta.com/img/index.png'
    },
    {
      property: 'og:description',
      content: description
    }
  ],
})

import Index from '@/views/Index.vue'
import AppWrapper from "@/components/AppWrapper.vue";

</script>

<template>
  <AppWrapper lang="en">
    <Index lang="en"></Index>
  </AppWrapper>
</template>

The important attributes are:

title: the page title that the user sees in the browser and the title included in the search engine index.
htmlAttrs.lang You can edit the value of the language attribute lang directly in the html root element
hreflang: You can specify different language versions of a page by inserting a <link> element with a hreflang attribute. Here we specify a link to the Chinese version of the homepage. Such an attribute can better facilitate the multilingual presentation of search engines.
meta.description: description in the meta tag, will be displayed as description in social media sharing.
og:*: specified by the Open Graph Protocol for social media links rendering that determine their title, description, and images when you share them on social media or chat software such as Twitter(X), Discord, etc.

headers should be injected at the page level, for pages in different languages, you should also inject headers in that language version.

Responsive in SSG

Of course, you want your website to look good (or at least not have overlap elements) on a widescreen computer, tablet, or phone, and to do that, you need to develop responsive web pages.

I personally use Vuetify to develop the UtilMeta official website, which has provided a Display system and breakpoints mechanism, which allows us to specify different display effects for different devices during development

For example

<v-row>
    <v-col :cols="display.xs.value ? 12 : 6">
    </v-col>
    <v-col :cols="display.xs.value ? 12 : 6">
    </v-col>
<v-row>

In this way, you can adjust the display of content on devices of different sizes through rows and columns, as shown in

Problems with v-if Syntax

Everything looks good, right? You find that you can really be responsive when debugging locally, but when the site goes live, you will find problems:

When the web page is loaded at first, it will also keep the style of the mobile side by default. It will not be adjusted to the appropriate style according to the screen size until the JS is loaded. In this way, when loading or refreshing, the user will see that the elements of the web page jumped in a few seconds. This is a very strange experience, so why does it cause such a problem?

After I opened the HTML generated by Vite-SSG, I found that SSG will directly freeze and render the configuration in the template when it is generated. For the responsive code similar to the following

<v-col :cols="display.xs.value ? 12 : 6">
  <h1 :style='{fontSize: display.xs.value ? "32px" : "48px"}'></h1>
</v-col>

In fact, when it is built into an HTML file, it will be rendered into

<div class="v-col-12">
  <h1 :style="font-size: 32px"></h1>
</div>

The rendering script will directly process display.xs.value (and other responsive conditions) as true, resulting in an HTML file with fixed styles, so the user can only re-render according to the size of the device when the responsive JavaScript code is loaded. It will cause the problem of transient element jump.

Saved by `@media`

So how do you properly handle the responsive styling of static pages? The answer I’ve explored is to use CSS @media rules, which allow you to create different style rules based on the size of the screen so that your responsive style fully controlled by CSS will render exactly according to the CSS rules when the page is rendered (thus dependent CSS is loaded). When different devices are refreshed, the rendering results adapted to the size of the corresponding device will also be presented directly, and the problem of element jump will not occur.

For example, I added a about-title class to the title of the About page and write it in the corresponding CSS.

  .about-title{
    font-size: 60px;
    line-height: 72px;
    max-width: 800px;
    margin: 6rem auto 0;
  }

  @media (max-width: 600px){
    .about-title{
      font-size: 36px;
      line-height: 48px;
      margin: 3rem auto 0;
    }
}

In this way, the title of the About page can be rendered according to @media the style defined in the block in devices with a size of less than 600px

Handling v-row / v-col

The grid system provided by Vuetify (v-row control row, v-col control column) can greatly improve the efficiency of responsive web page development, but we often need to keep the display of rows and columns responsive on different devices. However, the @media rules does not yet support different HTML classes for different device sizes, so how to deal with the responsiveness of the grid system in SSG applications?

The following is my practice: For a component that needs to switch the cols number of v-col on the mobile side, we can directly name the corresponding number of columns on the mobile as a class, such as

<v-row>
    <v-col :cols="6" class="xs-12-col">
    </v-col>
    <v-col :cols="6" class="xs-12-col">
    </v-col>
</v-row>

We then use @media rules to specify the grid style parameters for these classes directly in the mobile-sized device, such as

@media (max-width: 600px) {
    .xs-12-col{
      flex: 0 0 100%!important;
      max-width: 100%!important;
    }
    .xs-10-col{
      flex: 0 0 83.3%!important;
      max-width: 83.3%!important;
    }
    .xs-2-col{
      flex: 0 0 16.6%!important;
      max-width: 16.6%!important;
    }
}

In this way, our grid system can also support the responsive style in SSG without load jumps.

Deploy SSG website

Processing 404 elegantly

In the SSG static pages, the route supported by our website is pre-defined and generated, and other paths should return to 404 directly. However, in order to give users a better experience, the common practice is to make a 404 Notfound separate page and show it to users when there is no page in the access path. Make it easy for him to go back to the home page or other pages, such as the 404 page of UtilMeta’s official website.

Using Vite-SSG to achieve this effect is not difficult, you just need to add two components to the pages folder.

404.vue
[...all].vue

The contents of these two components are the same: the component code of the 404 page, [...all].vue will be used as the fallback return page of all page requests that do not match the route, and 404.vue will output an explicit route 404.html to facilitate direct redirection in nginx.

After completing our SSG page development, we can call the following command to build the page into a corresponding HTML file

vite-ssg build

For my UtilMeta website, the generated files are as follows

/dist
    /zh
        about.html
        py.html
        solutions.html
    404.html
    zh.html
    about.html
    index.html
    py.html
    solutions.html

Then, you can upload these static files to the page hosting service or build your own static server to provide access. The nginx configuration I used to build the static server of UtilMeta’s official website is as follows

server{
    listen 80;
    server_name utilmeta.com;
    rewrite ^/(.*)/$ /$1 permanent;

    location ~ /(css|js|img|font|assets)/{
        root /srv/utilmeta/dist;
        try_files $uri =404;
    }
    location /{
        root /srv/utilmeta/dist;
        index index.html;
        try_files $uri $uri.html $uri/index.html =404;
    }

    error_page 404 403 500 502 503 504 /404.html;

    location = /404.html {
        root /srv/utilmeta/dist;
    }
}

The reason for listen port 80 instead of port 443 in the configuration is that all the static resources of my website have been hosted to the CDN (including SSL certificates). The nginx here is configured as the source server of the CDN, so it is OK to provide the HTTP access only.

The role of nginx configuration rewrite ^/(.*)/$/$1 permanent is to map the directory access to the corresponding HTML file access, such as mapping https://utilmeta.com/zh/ to https://utilmeta.com/zh, otherwise Nginx will return a 403 Forbidden response.

Because the default build strategy for vite-ssg generates files located in a directory path index.vue as HTML files with the same name as the directory, rather than as index.html files placed in the directory, So if you don’t rewrite remove the end / of the path, https://utilmeta.com/zh/ will access the /zh/ directory directly, which is forbidden for nginx.

It is worth noting that the return of a 404 page should accompanied by a real 404 Response Code (Status Code) rather than a 200 OK (that is commonly referred to as a soft 404), because the search engine will only consider the route invalid if it detects the 404 response code, especially when your site is renovated, some routes of the old site will fail, and if they remain in the search engine results to mislead users, they will also cause great trouble to visitors.

In the above nginx configuration, we attach all try_files instructions with =404 at the end, to generate a 404 response code when no file is matched. Then we use error_page to specify the error page of common error response codes (including 404) as the /404.html page we wrote before, so that we can solve the problem of soft 404. All paths that cannot be matched will return the correct 404 response code and the 404 page.

Wrap up

Summarize what we have learned and accomplished.

Write an SSG official website project with Vite-SSG, and understand the page routing mode of the SSG project.
Write reusable multi-language SSG page components, and language switching function through route switching.
Use unhead to inject headers into each page, so that each page can be displayed correctly and beautifully on search engines and social media.
Use @media to solve problems in implementing SSG responsively for static pages, and the SSG responsive practice of the Vuetify grid system.
Elegantly handles the 404 of static pages, avoids soft 404, and improves the quality of page index and user experience.

If you find this article helpful, you can browse the utilmeta.com website I finally built in this article, or follow my X(Twitter), I will share some technical practices and projects from time to time.

Build User login/signup & RESTful APIs in 100 lines of Python

Xulin Zhou — Fri, 23 Feb 2024 05:17:39 +0000

For most applications, user is a must, we always need to develop user login, signup, query and update APIs. This post will walk you through a concise and flexible 100+ lines of Python code to implement such APIs.

We will use UtilMeta framework to build these APIs, It's an open-source Python meta backend framework, which supports the integration of Python frameworks like Django, Flask, FastAPI, and efficiently builds declarative RESTful APIs based on the Python type annotation standard

0. Installation

You can install UtilMeta framework using the following command

pip install utilmeta

UtilMeta requires Python >= 3.8

1. Create project

We use the meta setup command to create a new project.

meta setup demo-user

We will use Django as runtime framework of this project, so you can enter django when prompted to select backend

After the project is created, we need to configure the database connection of the service, open server.py, and insert the following code after the declaration of service

service = UtilMeta(
    __name__,
    name='demo-user',
    backend=django,
)

# new +++++
from utilmeta.core.server.backends.django import DjangoSettings
from utilmeta.core.orm import DatabaseConnections, Database

service.use(DjangoSettings(
    secret_key='YOUR_SECRET_KEY',
))

service.use(DatabaseConnections({
    'default': Database(
        name='db',
        engine='sqlite3',
    )
}))

In the inserted code, we declare the configuration information of Django and the configuration of the database connection. Because Django uses the app to manage the data model, we use the following command to create an app named user

meta add user

You can see that a new folder named user has been created in our project folder, which includes

/user
    /migrations
    api.py
    models.py
    schema.py

The migrations folder is where Django handles the database migrations of the models

Once the app is created, we insert a line into the DjangoSettings of server.py to specify the app.

service.use(DjangoSettings(
    secret_key='YOUR_SECRET_KEY',
    apps=['user']
))

So far, we have completed the configuration and initialization of the project.

2. Write user model

The user APIs depend on the "user", so before developing the API, we should write the user’s data model. We open user/models.py and write

from django.db import models
from utilmeta.core.orm.backends.django.models import AbstractSession, PasswordField

class User(models.Model):
    username = models.CharField(max_length=20, unique=True)
    password = PasswordField(max_length=100)
    signup_time = models.DateTimeField(auto_now_add=True)

class Session(AbstractSession):
    user = models.ForeignKey(
        User, related_name='sessions', 
        null=True, default=None, 
        on_delete=models.CASCADE
    )

We write a User model firstly that contains

username: The username field which is required to be unique ( unique=True )
password: The password field using PasswordField to auto-encrypt the input password (with pbkdf2)
signup_time: The signup time field

In addition to the User model, we have also written a Session model for users to record user sessions and login state. We will implement user login and authentication through this model.

Connect database

After we write the data model, we can use the migration command provided by Django to easily create the corresponding data table. Since we use SQLite, we do not need to install the database software in advance. We only need to run the following two commands to complete the creation of the database.

meta makemigrations
meta migrate

When you see the following output, you have finished creating the database

Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying user.0001_initial... OK

The database migration command created a SQLite database named db in the project folder according to the database configuration in server.py , where the table of User and Session models has been created

3. Session and Authentication

After writing the user models, we can start to develop the authentication logic. We create a new file named auth.py in the user folder and write the configuration of session and user authentication.

from utilmeta.core import auth
from utilmeta.core.auth.session.db import DBSessionSchema, DBSession
from .models import Session, User

USER_ID = '_user_id'

class SessionSchema(DBSessionSchema):
    def get_session_data(self):
        data = super().get_session_data()
        data.update(user_id=self.get(USER_ID))
        return data

session_config = DBSession(
    session_model=Session,
    engine=SessionSchema,
    cookie=DBSession.Cookie(
        name='sessionid',
        age=7 * 24 * 3600,
        http_only=True
    )
)

user_config = auth.User(
    user_model=User,
    authentication=session_config,
    key=USER_ID,
    login_fields=User.username,
    password_field=User.password,
)

In this code, SessionSchema is the core engine that processes and stores Session data, session_config declares the Session configuration with Session model and engine we just wrote, and configures the corresponding Cookie policy

We use session store based on database to simply our tutorial, in practice, we often use cache+db as the store, you can find more in Session Authentication

We also declare the user authentication configuration user_config with the following params

user_model: Specify the user model for authentication, which is the User model I wrote in the previous section.
authentication: Specify the authentication method. We pass session_config in to declare that user authentication is performed using Session.
key: Specify the key of the current user ID in the session data
login_fields: Fields that can be used for login, such as username, email, etc., which need to be unique.
password_field: The user’s password field. Declaring these allows UtilMeta to automatically handle the login verification logic for you.

4. Write user API

Signup API

First, we will write the user signup API. It should receive the user name and password fields, complete the signup after verifying that the user name is not occupied, and return the newly registered user data.

We open the user/api.py and write

from datetime import datetime
from utilmeta.core import api, orm
from utilmeta.utils import exceptions
from .models import User
from . import auth

class SignupSchema(orm.Schema[User]):
    username: str
    password: str

class UserSchema(orm.Schema[User]):
    id: int
    username: str
    signup_time: datetime

@auth.session_config.plugin
class UserAPI(api.API):
    @api.post
    def signup(self, data: SignupSchema = request.Body) -> UserSchema:
        if User.objects.filter(username=data.username).exists():
            raise exceptions.BadRequest('Username exists')
        data.save()
        auth.user_config.login_user(
            request=self.request,
            user=data.get_instance()
        )
        return UserSchema.init(data.pk)

We use @api decorator to define the API functions that provide API service, which contains HTTP methods like GET / POST / PUT / PATCH / DELETE, we are using the POST method in the signup API. You can use the first param in the decorator to specify the API's path, if empty like the above example, the API's path will be the function's name (signup)

We declared the request body of signup API as SignupSchema. so that UtilMeta will automatically parse and covert request body to a SignupSchema instance, the invalid request will be rejected by UtilMeta and with a 400 response

The logic in the signup API function is

Detect whether the in username the request has been registered
Call data.save() method to save the signup data
Login the registered user to the current request using login_user
Returns after initializing the new user’s data to a UserSchema instance using UserSchema.init(data.pk)

UtilMeta has developed an efficient declarative ORM mechanism, We use orm.Schema[User] to define a Schema class with the User model injected, so that we can use the methods of the schema class to create, update, and serialize data. You can find more in Data Query and ORM Document

We can also find that a decorator named @auth.session_config.plugin is plugin to the UserAPI class. This is where the Session configuration is applied to the API. This plugin can save the Session data after each request and patch the response with corresponding Set-Cookie header

Login & Logout API

Next, we'll write the user’s login and logout APIs

from datetime import datetime
from utilmeta.core import api, orm, request
from utilmeta.utils import exceptions
from .models import User
from . import auth
import utype

class LoginSchema(utype.Schema):
    username: str
    password: str

@auth.session_config.plugin
class UserAPI(api.API):
    @api.post
    def signup(self): ...

    # new ++++
    @api.post
    def login(self, data: LoginSchema = request.Body) -> UserSchema:
        user = auth.user_config.login(
            request=self.request,
            ident=data.username,
            password=data.password
        )
        if not user:
            raise exceptions.PermissionDenied('Username of password wrong')
        return UserSchema.init(user)

    @api.post
    def logout(self, session: auth.SessionSchema = auth.session_config):
        session.flush()

In the login API, we call the login() method in our authentication configuration to complete the login simply. Since we have configured the login field and password field, UtilMeta can help us complete the password verification and login automatically. If the login is successful, the corresponding user instance is returned. So we can throw an error if the login() result is None, and after a successful login, we can call UserSchema.init to return the login user data to the client.

For the logout API, we just need to empty the session data of current request, We use the declared session_config as the default of the function parameter to receive the Session object of the current request and use session.flush() to empty it.

Get & Update user data

When we understand the usage of declarative ORM, it is very simple to write the get & update API of User

from datetime import datetime
from utilmeta.core import api, orm, request
from utilmeta.utils import exceptions
from .models import User
from . import auth
import utype

class UserUpdateSchema(orm.Schema[User]):
    id: int = orm.Field(no_input=True)
    username: str = orm.Field(required=False)
    password: str = orm.Field(required=False)

@auth.session_config.plugin
class UserAPI(api.API):
    @api.post
    def signup(self): ...
    @api.post
    def login(self): ...
    @api.post
    def logout(self): ...

    # new ++++
    def get(self, user: User = auth.user_config) -> UserSchema:
        return UserSchema.init(user)

    def put(self, data: UserUpdateSchema = request.Body, 
            user: User = auth.user_config) -> UserSchema:
        data.id = user.pk
        data.save()
        return UserSchema.init(data.pk)

After we declare the user authentication configuration, we can declare user: User = auth.user_config in the API function parameters to get the instance of the current request user in any API that requires user login. If the request is not logged in, UtilMeta will automatically process and return a 401 Unauthorized response

In the get API, we directly serialize the current request user using UserSchema and return it to the client
In the put API, we assign the current request user's ID to the id field of UserUpdateSchema, and return the updated user data after saving.

Since we can’t allow the requesting user to arbitrarily specify the user ID to be updated, we use the no_input=True option for id field, which is actually a common practice, that is a user can only update his own information.

If your API function using the name of HTTP methods (such as get/put/patch/post/delete), it will bind the method and mount the same route of the API class, these methods are called core methods of the API class

At this point, our API is all developed.

Mount API

To provide access to our developed UserAPI, we need to mount it on the root API of the service. Let’s go back to server.py and modify the declaration of the RootAPI.

# new +++
service.setup()
from user.api import UserAPI

class RootAPI(api.API):
    user: UserAPI

service.mount(RootAPI, route='/api')

We mount the developed UserAPI to the RootAPI's user property, which means that the UserAPI's path is mounted to /api/user, the endpoints in UserAPI will follow the path, like

GET /api/user: Get the current user of the request
PUT /api/user: Update the current user of the request
POST /api/user/login: User login
POST /api/user/logout: User logout
POST /api/user/signup: User signup

This mounting syntax is convenient for defining tree-like API structure

You should call service.setup() before import any Django models to complete the setup of Django

5. Run the API

Run the API service using the following command in the project folder

meta run

Or you can use

python server.py

When you see the following output, the service has started successfully

Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

You can alter the host and port params of UtilMeta service in server.py to change the address of the API service

6. Debug API

After starting our API service, we can debug the APIs using the client in UtilMeta, let's create a new file named test.py in the project directory and write

from server import service

if __name__ == '__main__':
    with service.get_client(live=True) as client:
        r1 = client.post('user/signup', data={
            'username': 'user1',
            'password': '123123'
        })
        r1.print()
        r2 = client.get('user')
        r2.print()

It contains the debug code for the signup and gets APIs, when we started the service and run test.py, we can see the following output like

Response [200 OK] "POST /api/user/signup"
application/json (76)
{'username': 'user1', 'id': 1, 'signup_time': '2024-01-29T12:29:33.684594'}

Response [200 OK] "GET /api/user"
application/json (76)
{'username': 'user1', 'id': 1, 'signup_time': '2024-01-29T12:29:33.684594'}

It means our signup and get APIs worked,

In the with code block, client will store the Set-Cookie in the response the send in the following requests, so we can see the session works just like the browser

We can also test the login, logout, and update APIs, the complete examples are as follows

from server import service

if __name__ == '__main__':
    with service.get_client(live=True) as client:
        r1 = client.post('user/signup', data={
            'username': 'user1',
            'password': '123123'
        })
        r1.print()
        # Response [200 OK] "POST /api/user/signup"
        # application/json (75)
        # {'username': 'user1', 'id': 1, 'signup_time': '2024-01-29T13:29:03.336134'}
        r2 = client.get('user')
        r2.print()
        # Response [200 OK] "GET /api/user"
        # application/json (75)
        # {'username': 'user1', 'id': 1, 'signup_time': '2024-01-29T13:29:03.336134'}
        r3 = client.post('user/logout')
        r3.print()
        # Response [200 OK] "POST /api/user/logout"
        # text/html (0)
        r4 = client.get('user')
        r4.print()
        # Response [401 Unauthorized] "GET /api/user"
        # text/html (0)
        r5 = client.post('user/login', data={
            'username': 'user1',
            'password': '123123'
        })
        # Response [200 OK] "POST /api/user/login"
        # application/json (75)
        # {'username': 'user1', 'id': 1, 'signup_time': '2024-01-29T13:29:03.336134'}
        r5.print()
        r6 = client.get('user')
        r6.print()
        # Response [200 OK] "GET /api/user"
        # application/json (75)
        # {'username': 'user1', 'id': 1, 'signup_time': '2024-01-29T13:29:03.336134'}
        r7 = client.put('user', data={
            'username': 'user-updated',
            'password': '123456'
        })
        r7.print()
        # Response [200 OK] "PUT /api/user"
        # application/json (82)
        # {'username': 'user-updated', 'id': 1, 'signup_time': '2024-01-29T13:44:30.095711'}

References

Source Codeof this post
UtilMeta: framework used in this post

If you have any problem, you are welcome to join the discord server of UtilMeta to discuss

UtilMeta - a meta backend framework for Python

Xulin Zhou — Tue, 20 Feb 2024 16:08:25 +0000

Hi~ I'm Xulin Zhou (@voidZXL), I recently open-sourced my 4-year project: UtilMeta

Introduction

UtilMeta is a progressive meta-framework for backend applications, which efficiently builds declarative RESTful APIs based on the Python type annotation standard, and supports the integration of mainstream Python frameworks as runtime backend such as Django, Flask, FastAPI(Starlette) and Sanic

Installation

pip install utilmeta

Core features

Declarative RESTful API

Using the declarative power from UtilMeta, you can easily write APIs with auto request validation, declarative ORM in UtilMeta can handle relational queries concisely without N+1 problem, both sync and async queries are supported

from utilmeta.core import api, orm
from django.db import models

class User(models.Model):
    username = models.CharField(max_length=20, unique=True)

class Article(models.Model):
    author = models.ForeignKey(User, related_name="articles", on_delete=models.CASCADE)
    content = models.TextField()

class UserSchema(orm.Schema[User]):
    username: str
    articles_num: int = models.Count('articles')

class ArticleSchema(orm.Schema[Article]):
    id: int
    author: UserSchema
    content: str

class ArticleAPI(api.API):
    async def get(self, id: int) -> ArticleSchema:
        return await ArticleSchema.ainit(id)

if you request the ArticleAPI like GET /article?id=1, you will get the result like

{
  "id": 1,
  "author": {
    "username": "alice",
    "articles_num": 3
  },
  "content": "hello world"
}

This conforms to what you declared, and the OpenAPI docs will be generated automatically like

The concise declarative development can reduce a significant amount of code in building APIs, for example, UtilMeta implemented the Realworld blog APIs with only 600+ lines of code, while others:

Highly Flexible & Extensible

UtilMeta is highly flexible with a series of plugins including authentication (Session/JWT), CORS, rate limit, retry, and can be extended to support more features.

Full-lifecycle DevOps Solution

The UtilMeta Platform will provide the full-lifecycle DevOps solution for UtilMeta framework with API Docs, Debug, Logs, Monitoring and Alerts (currently in a Beta waitlist)

Quick Start

You can start using UtilMeta by these case tutorials from easy to complex:

If you prefer to learn from a specific feature, you can refer to

Handle Request: How to handle path, query parameters, request body, file upload, request headers and cookies.
API Class and Routing How to use API class mounts to define tree-like API routing, and use hooks to easily reuse code between APIs, handle errors, and template responses.
Schema query and ORM How to use Schema to declaratively write the CRUD query, and ORM operations required by a RESTful interface.
API Authentication: How to use Session, JWT, OAuth and other methods to authenticate the request of the interface, get the current request's user and simplify the login operation
Config, Run & Deploy: How to configure the run settings, startup, and deployment of a service using features such as declarative environment variables
Migrate from current project How to progressively integrate UtilMeta API to an existing backend project or migrate to UtilMeta

Community

It's my 1st post in this community, if you find this project useful or interesting, please consider giving us a ⭐ in the Github Repo 🥰

and you can join our Discord Server of UtilMeta to get the latest updates of the project and discuss with the community~

DEV Community: Xulin Zhou

Building a Realworld blog backend in 600 lines of Python

0. Intro

1. Create project

Install dependencies

setup command

2. Write the data model

Create an application

User model

Article & Comment Model

Add m2m model

Migrate to database

3. User APIs and Authentication

JWT authentication

Environment variables

User API

Profile API

4. Article & Comment APIs

Article API structure

Write Article Schema

Field Mode

Dynamic query field

Article Query API

Using hooks to reuse logic

Comment API

5. Mount API and handle errors

6. Configure and run

Time configuration

Environment variables

Run the project

7. Connect and Manage

API

Data

Logs

Related Links

Building an SEO-friendly responsive i18n website using Vite-SSG + Vuetify3

Why not SPA?

What is the appropriate way?

SSG project structure

Handle multi-language pages

Language switching

Inject HTML headers into the page

Responsive in SSG

Problems with v-if Syntax

Saved by @media

Deploy SSG website

Processing 404 elegantly

Wrap up

Build User login/signup & RESTful APIs in 100 lines of Python

0. Installation

1. Create project

2. Write user model

Connect database

3. Session and Authentication

4. Write user API

Signup API

Login & Logout API

Get & Update user data

Mount API

5. Run the API

6. Debug API

References

UtilMeta - a meta backend framework for Python

Introduction

Installation

Core features

Declarative RESTful API

Highly Flexible & Extensible

Full-lifecycle DevOps Solution

Quick Start

Community

Saved by `@media`