Profiles Endpoints

This page details the Profiles endpoints in The Wall API, responsible for tracking and managing cost calculations related to wall construction.

Table of Contents

1. Overview
2. API Requests Flow Diagram
3. Profiles Endpoints
4. Profiles Endpoints Views
   4.1 Class Architecture
   4.2 Throttling Mechanisms
   4.3 OpenAPI Schema Documentation
   4.4 Core DRF Components
5. Wall Data ORM Representation
   5.1 Data Model Overview
   5.2 Key Operational Behaviors

1. Overview

• Construction progress querying is a core functionality in The Wall API, allowing users to perform the following operations:

  ✔ Retrieve daily construction cost for a specific profile.
  ✔ Retrieve aggregated daily cost across all profiles.
  ✔ Retrieve total accumulated build cost for all profiles.
  ✔ Retrieve daily amounts of ice used for a specific profile.

• Authentication is required for all requests, and API rate limits ensure fair access to resources.

• The cost calculations are based on wall construction simulations, ensuring that each request retrieves precise cost estimates for a specific profile or the entire wall.

---

2. API Requests Flow Diagram

The following diagram illustrates the API request flow for profiles endpoints queries. It outlines how the system processes requests for cost calculations, handles concurrent tasks, and determines whether to fetch cached results, perform synchronous calculations, or delegate computations to Celery.

View full image

Return to Top

---

3. Profiles Endpoints

Action	Endpoint	Requires Authentication?
Daily Profile Cost	/api/v2/profiles/<int:profile_id>/overview/<int:day>/	✅ Yes
Daily Wall Cost	/api/v2/profiles/overview/<int:day>/	✅ Yes
Total Wall Cost	/api/v2/profiles/overview/	✅ Yes
Daily Profile Ice Amount	/api/v2/profiles/<int:profile_id>/days/<int:day>/	✅ Yes

💡 API Access Overview - Full API endpoints breakdown and applied throttling rates.

💡 Detailed Cost and Resource Calculations - In-depth explanations of cost computation logic.

💡 Detailed OpenAPI Documentation - Comprehensive details on each profiles endpoint and its parameters.

Return to Top

---

4. Profiles Endpoints Views

Wall progress tracking data in The Wall API is retrieved through dedicated Django Rest Framework (DRF) views, which handle authentication, request validation, and structured API documentation.

4.1 Class Architecture

• Base Class: ProfilesBaseView (inherits APIView)

  • Centralizes throttling (UserRateThrottle), and request validation.
  • Implements a shared request processing method (process_profiles_request) to extract query parameters, validate them, and retrieve simulation data.
  • Provides structured error handling and response formatting for all profile-related endpoints.

• Derived Views:

  • ProfilesDaysView – Retrieves daily ice usage for a specific profile.
  • ProfilesOverviewView – Returns aggregated costs for the entire wall construction.
  • ProfilesOverviewDayView – Fetches daily total cost for all actively constructed profiles.
  • SingleProfileOverviewDayView – Retrieves cost for a specific profile on a given day.

• Design Rationale

  • Separation of concerns: ProfilesBaseView ensures consistent validation, authentication, and data retrieval, while each derived view is responsible for a specific type of cost computation, reducing redundant logic.
  • Extendable API documentation: Each view applies @extend_schema from drf-spectacular, ensuring distinct and structured documentation for every endpoint.

Return to Top

4.2 Throttling Mechanisms

• API requests are rate-limited under the Authenticated throttle scope, preventing excessive usage.
• The API ensures optimized resource distribution by limiting requests based on demand.

💡 For more details on API throttling, see the API Throttling page.

Return to Top

4.3 OpenAPI Schema Documentation

• Profiles endpoints are documented with DRF Spectacular, ensuring structured and consistent schema definitions.

💡 Check DRF Spectacular for API documentation and schema generation details.

Return to Top

4.4 Core DRF Components

The following DRF files manage profiles endpoints-related data:

• the_wall_api/views.py – Defines API views for retrieving cost and ice usage data.

• config/urls.py – Maps profiles API endpoints.

• the_wall_api/utils/api_utils.py – Manages profiles endpoints registration within the centralized API configuration.

• the_wall_api/serializers.py – Structures and validates the profiles endpoints API requests.

• config/settings.py – Controls authentication, permissions, and rate-limiting configuration.

  • Global authentication and permissions are configured in REST_FRAMEWORK:

    REST_FRAMEWORK = {
        'DEFAULT_AUTHENTICATION_CLASSES': [
            'rest_framework.authentication.TokenAuthentication',
        ],
        'DEFAULT_PERMISSION_CLASSES': [
            'rest_framework.permissions.IsAuthenticated',
        ],
    }

    💡 These settings enforce token-based authentication, ensuring only authenticated users can query wall configuration data.

Return to Top

---

5. Wall Data ORM Representation

5.1 Data Model Overview

• The Wall API uses database models to manage cost-tracking for different construction profiles.

  • WallConfig: Stores wall configurations and associated cost parameters.
    💡 See WallConfig ORM Model.

  • Wall: Represents a simulated build using a WallConfig.
    💡 Check Wall ORM Model.

  • WallProgress: Tracks daily progress, costs, and ice usage.
    💡 See WallProgress ORM Model.

Return to Top

5.2 Key Operational Behaviors

• Each Wall instance represents a complete construction simulation, tracking costs and resource consumption.

• Daily cost calculations are performed per WallProgress instance, which records the ice amount used and monetary cost for each simulated day.

• Aggregated daily costs combine all ongoing builds for a given day.

• Total cost computations aggregate all recorded daily costs from all builds.

• The profiles' progress and costs are stored in a structured manner, ensuring accurate and scalable cost estimation for different construction scenarios.

---

Next:   Error Handling
Back to: File Management Endpoints

Return to Top
DTS Index
Home Page

---