Skip to content

Category

ViniciusPeralta edited this page Mar 6, 2026 · 8 revisions
erDiagram
   direction LR
   Category ||--o{ Tag : contains
   Category {
      long id
      string name
      string color
      string icon
      boolean active
      long userId
   }
   Tag {
      long id
      string name
      Category category
   }
Loading

Category domain is used to, as its name suggests, categorize financial transactions in order to make it easier to identify spending and income patterns, organize financial records, and generate meaningful insights.

A category represents a logical classification of a transaction, such as "Food", "Salary", "Transport" or "Entertainment". Each category can optionally include a color and an icon to improve visual identification within the user interface.

Also, categories can have at most 10 Tags, tags act as secondary classification elements, allowing more granular grouping within a category.

Services

Here we have detailed information about the services related to API-CoreData Category domain such as request parameters needed, endpoint and a flowchart.

Registration

To register a new category, you need to provide the following object in the body of the request:

{
    "name": "Food",
    "color": "#FF6D00",
    "icon": "🍔"
}

Rules:

  • name: Required, must be unique for the user, and should not exceed 20 characters;
  • color: Optional, must be a valid hex color code (e.g., #FF6D00);
  • icon: Optional, must be a single emoji character.

The system will validate the information received to check if all data is valid and if the category does not already exists.

Endpoint

[POST] /api/core/category

Flowchart

flowchart
    A((START)) --> B
    B{Request valid?} -- Yes --> C
    B -- No --> D[Return 400 Bad Request]
    C[Check if category already exists] --> E
    E{Category already exists?} -- No --> F
    E -- Yes --> G[Return 409 Conflict]
    F[Save new user] --> H[Delete user cache for category listing]
    H --> I[Return 200 - Created]

    style A stroke:#FF6D00
    style D stroke:#D50000
    style G stroke:#D50000
    style I stroke:#00C853
Loading

Listing

To list categories you can use the following filters in the request parameters:

  • pageNumber: The page number to retrieve (optional, default is 0);
  • pageSize: The number of items per page (optional, default is 10);
  • search: A search term to filter categories by name (optional);

Endpoint

[GET] /api/core/category/list

Flowchart

flowchart
    A((START)) --> B
    B{Cache exists for request parameters?} -- No --> D[Query database for categories]
    B -- Yes --> C[Return 200 - Cached response]
    D --> E[Create cache for request parameters]
    E --> F[Return 200 - Categories list]

    style A stroke:#FF6D00
    style C stroke:#00C853
    style F stroke:#00C853
Loading

Get by ID

To get a category by its ID, you need to provide the category ID as a path parameter in the request.

Endpoint

[GET] /api/core/category/{categoryId}

FlowChart

flowchart
    A((START)) --> B
    B{Category with provided ID \n exists for the user?} -- Yes --> C[Return 200 - Category details]
    B -- No --> D[Return 404 Not Found]
    
    style A stroke:#FF6D00
    style D stroke:#D50000
    style C stroke:#00C853
Loading

Update

To update an existing category, you need to provide the following object in the body of the request:

{
  "id": 1,
  "name": "Food",
  "color": "#FF6D00",
  "icon": "🍔",
  "tags": [
    {
      "id": 1,
      "name": "Restaurant"
    },
    {
      "id": null,
      "name": "Groceries"
    }
  ]
}

Rules:

  • id: Required, must be the ID of an existing category for the user;
  • name: Required, must be unique for the user (excluding the current category), and should not exceed 20 characters;
  • color: Optional, must be a valid hex color code (e.g., #FF6D00);
  • icon: Optional, must be a single emoji character;
  • tags: Optional, can contain up to 10 tags. Each tag must have a name that does not exceed 20 characters. If an ID is provided for a tag, it must correspond to an existing tag within the category; if the ID is null, a new tag will be created.

The system will validate the information received to check if all data is valid, if the category exists, and if the new name does not conflict with other categories.

Endpoint

[PATCH] /api/core/category

Flowchart

flowchart
    A((START)) --> B
    B[Query database for category with provided ID] --> C
    C{Category exists for the user?} -- Yes --> D{Category name is unique for the user?}
    C -- No --> E[Return 404 - Not Found]
    D -- Yes --> F[Update category and tags]
    D -- No --> G[Return 400 - Bad Request]
    F --> H[Delete user cache for category listing]
    H --> I[Return 200 - Updated category details]
    
    style A stroke:#FF6D00
    style E stroke:#D50000
    style G stroke:#D50000
    style I stroke:#00C853
Loading

⚠️ Checkout update Tag service to understand the service flow.

Delete by ID

To delete an existing category, you need to provide the category ID as a path parameter in the request.

Endpoint

[DELETE] /api/core/category/{categoryId}

Flowchart

flowchart
    A((START)) --> B
    B[Query database for category with provided ID] --> C
    C{Category exists for the user?} -- Yes --> D[Delete the category logically]
    C -- No --> E[Return 404 - Not Found]
    D --> F[Delete user cache for category listing]
    F --> G[Return 200 - Category deleted successfully]
    
    style A stroke:#FF6D00
    style E stroke:#D50000
    style G stroke:#00C853
Loading