The Best Folder Structure for Your API
Tags: webdev, beginners, programming
Published: 2024-04-21 17:08:41

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.

```python
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
```

```plaintext
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`

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

`UsersUpdateController.py`

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

`UsersGetController.py`

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

`UsersAllController.py`

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

```plaintext
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`

```python
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**](mailto: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**](http://x.com/sotergreco)