The Best Folder Structure for Your API

If you start creating an API from scratch without using any framework, you might find yourself wondering how to structure your folders. Although there is no universal standard for doing this.

However, I believe there are some guidelines everyone should follow to keep their code clean and organized. Let's take a look at how I structure my folders in several applications I have created.

Controllers

Every API requires a controllers folder. This folder contains the logic for handling requests and defining what each request will do. For instance, you could create a UsersController.py file.

class UsersController:
    def store(request):
        # store a new user

    def update(request):
        # update a new user

    def get(request):
        # get single user

    def all(request):
        # get all users

api/
├─ Controllers/
│  ├─ UserController.py

This is one approach to organizing controllers. Another approach is to create separate files for each user action. For example:

UsersCreateController.py

class UsersCreateController:
    def execute():
        # store a new user

UsersUpdateController.py

class UsersUpdateController:
    def execute():
        # update a user

UsersGetController.py

class UsersGetController:
    def execute():
        # get a single user

UsersAllController.py

class UsersAllController:
    def execute():
        # get all users

api/
├─ Controllers/
│  ├─ UsersControllers/
│  │  ├─ UsersCreateController.py
│  │  ├─ UsersUpdateController.py
│  │  ├─ UsersGetController.py
│  │  ├─ UsersAllController.py

Services

Services in some cases can come hand in hand with controller but they are not the same thing. Services are pieces of code that are reusable across many controllers. So we abstract them in their own folder and files. An example service can be ConvImageService.py

class ConvImageService:
    def execute(image):
        # convert image service code

Models

Certainly, models are integral components in virtually every API. Typically, models are classes designed to handle and process our data. They serve as the backbone of the application, defining the data structure, enforcing validation rules, and encapsulating the logic necessary for data manipulation.

By using models, developers can ensure that data adheres to specified formats and behaviors, thus maintaining data integrity throughout the application. This structured approach not only helps in organizing the code better but also enhances maintainability and scalability by allowing changes in data requirements to be implemented more efficiently.

Config

As its name suggests, the config directory can contain configurations for any part of the application. For example, a config.py file might store environment variables for the database, email services, or any external APIs. The config.py file typically uses environment variables from an .env file, which, of course, should not be pushed to Git.

Additionally, the config.py file can contain general application settings, such as database_type, email_service_provider, and so on.

Conclusion

In conclusion, structuring folders in your API is crucial for maintaining a clean and organized codebase. By categorizing code into logical sections such as Controllers, Services, Models, and Config, you enhance the scalability and maintainability of your application.

Adhering to these best practices not only simplifies the development process but also makes it easier for other developers to understand and contribute to your project. Remember, the key to a successful API is not just in its functionality but also in its structure and organization.

Thanks for reading, and I hope you found this article helpful. If you have any questions, feel free to email me at kourouklis@pm.me, and I will respond.

You can also keep up with my latest updates by checking out my X here: x.com/sotergreco