Repository navigation
Category
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
}
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.
Here we have detailed information about the services related to API-CoreData Category domain such as request parameters needed, endpoint and a flowchart.
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.
[POST] /api/core/category
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
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);
[GET] /api/core/category/list
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
To get a category by its ID, you need to provide the category ID as a path parameter in the request.
[GET] /api/core/category/{categoryId}
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
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.
[PATCH] /api/core/category
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
To delete an existing category, you need to provide the category ID as a path parameter in the request.
[DELETE] /api/core/category/{categoryId}
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
© 2026 CashFlow Project
CoreData Service Documentation
Maintained by the CashFlow Team.
For improvements or questions, please open an Issue in this repository.