REST Services

This section contains comprehensive documentation for REST service operations in FlexBase applications. Each document demonstrates the complete flow from API controller to database operations, including event publishing and subscriber processing.

Available REST Operations

Communication Architecture

• REST Client Communication - Complete communication flow explanation

• DTOs vs Request/Response Objects distinction

• Mapping between internal and external contracts

• RESTClient implementation patterns

• Error handling and resilience strategies

Insert Operations

• Insert Example - AddToShipping flow demonstrating POST operations

• Complete flow from POST request to event publishing

• PreBus validation pipeline with business rules

• Command handler processing and domain logic

• Event-driven architecture with subscribers

• RESTClient integration for external communication

Update Operations

• Update Example - UpdateShipping flow demonstrating PUT operations

• Entity lookup and validation before updating

• PreBus validation with business rules

• Domain model state management

• Event publishing for change notifications

• RESTClient integration for external updates

Query Operations

• Get By ID Example - GetShippingInfoById flow demonstrating single entity retrieval

• Fast indexed lookup by unique identifier

• AutoMapper for entity-to-DTO transformation

• Error handling with 404 responses

• Optimized for single entity details

• RESTClient integration for external data

• Get List Example - GetShippingDetails flow demonstrating list retrieval

• Simple IEnumerable<T> without pagination

• Optimized for dropdown/lookup scenarios

• Lightweight data transfer

• Fast loading for small datasets

• RESTClient integration for external lists

• Get Paged List Example - GetShippingPagedList flow demonstrating paginated retrieval

• FlexiPagedList<T> with pagination metadata

• Optimized for data grids and large datasets

• Built-in pagination with page numbers and sizes

• Rich metadata for frontend integration

• RESTClient integration for external pagination

• Get Single Example - GetShippingSingle flow demonstrating flexible single entity retrieval

• Multiple criteria for entity identification

• Flexible filtering beyond just ID

• Business logic for complex lookups

• Alternative key support (tracking numbers, order IDs, etc.)

• RESTClient integration for external lookups

Delete Operations

• Delete Example - DeleteShipping flow demonstrating hard delete operations

• Physical removal from database

• PreBus validation before deletion

• Event publishing for cleanup operations

• Audit trail considerations

• RESTClient integration for external deletions

• Soft Delete Example - SoftDeleteShipping flow demonstrating soft delete operations

• Data preservation with deletion flag

• Recovery capabilities

• Complete audit trail

• Query filtering for soft-deleted items

• RESTClient integration for external soft deletes

REST Service Architecture

Complete Communication Flow Pattern

External System → RESTClient → Request DTO → Mapping → Internal DTO → Controller → Service → Domain → Database
                ↑                                                                                    ↓
External System ← RESTClient ← Response DTO ← Mapping ← Internal DTO ← Controller ← Service ← Domain ← Database

Internal Flow Pattern (Write Operations)

HTTP Request → Controller → Service → PreBus Plugins → Command Handler → Domain Model → Database → Event Publishing → Subscribers

Internal Flow Pattern (Read Operations)

HTTP Request → Controller → Service → Query Handler → Database → AutoMapper → Response

External Communication Pattern

Internal DTO → Mapping → Request DTO → RESTClient → External System
External System → RESTClient → Response DTO → Mapping → Internal DTO

Key Components

Controllers

• API entry points with HTTP method attributes

• Parameter binding and validation

• Response type declarations

• Error handling and status codes

Services

• Business orchestration layer

• PreBus processing for validation

• Command/Query resolution

• Result processing

• RESTClient integration

RESTClients

• External system communication

• HTTP client management

• Request/Response serialization

• Error handling and resilience

• Retry policies and circuit breakers

Request/Response DTOs

• External system contracts

• Serialization/Deserialization

• External validation rules

• Version management

Internal DTOs

• Application contracts

• Business validation rules

• FlexBase integration

• Internal data structures

Mapping Layer

• DTO to Request/Response transformation

• Field mapping and conversion

• Validation rule translation

• Contract versioning

PreBus System

• Plugin-based validation pipeline

• Business rule sequences

• Data packet context

• Error collection and reporting

Command Handlers

• Data processing for write operations

• Domain model interaction

• Database persistence

• Event publishing

• RESTClient integration

Query Handlers

• Data retrieval for read operations

• Database query building

• AutoMapper integration

• Result transformation

• RESTClient integration

Domain Models

• Business logic implementation

• State management

• Data validation

• Business rules

Event System

• Asynchronous processing

• Event publishing

• Subscriber processing

• Side effects handling

HTTP Methods and Use Cases

HTTP Method	Use Case	Example	Response
POST	Create new entity	AddToShipping	201 Created
PUT	Update existing entity	UpdateShipping	200 OK
GET	Retrieve data	GetShippingInfoById	200 OK / 404 Not Found
DELETE	Remove entity	DeleteShipping	200 OK

Response Patterns

Success Responses

• 201 Created: New entity created successfully

• 200 OK: Operation completed successfully

• 200 OK with Data: Query operations with results

Error Responses

• 400 Bad Request: Invalid parameters or validation errors

• 404 Not Found: Entity not found (for GET operations)

• 500 Internal Server Error: Server or database errors

Data Transfer Objects (DTOs)

Input DTOs

• Request body parameters for POST/PUT operations

• Query parameters for GET operations

• URL parameters for DELETE operations

Output DTOs

• Response data for successful operations

• Error information for failed operations

• Pagination metadata for paged results

Best Practices

Controller Design

• Use appropriate HTTP methods

• Declare response types

• Handle errors gracefully

• Validate input parameters

Service Layer

• Keep business logic in services

• Use PreBus for validation

• Handle command/query resolution

• Process results appropriately

Query Operations

• Use appropriate query base classes

• Implement efficient query building

• Apply proper filtering

• Use AutoMapper for transformations

Command Operations

• Validate business rules

• Handle domain logic

• Publish events appropriately

• Log operations

Error Handling

• Use appropriate HTTP status codes

• Provide meaningful error messages

• Log errors appropriately

• Handle exceptions gracefully

Performance Considerations

Query Optimization

• Use database indexes effectively

• Implement efficient query building

• Apply appropriate filtering

• Use pagination for large datasets

Command Optimization

• Validate early in the pipeline

• Use efficient database operations

• Implement proper logging

• Handle events asynchronously

Caching Strategies

• Cache frequently accessed data

• Use appropriate cache keys

• Implement cache invalidation

• Consider cache warming

Security Considerations

Input Validation

• Validate all input parameters

• Use PreBus for business rule validation

• Sanitize user input

• Implement proper authorization

Data Protection

• Use appropriate DTOs

• Implement data masking

• Handle sensitive data carefully

• Follow security best practices

Testing Strategies

Unit Testing

• Test each component independently

• Mock dependencies appropriately

• Test error scenarios

• Verify business logic

Integration Testing

• Test complete flows

• Verify database operations

• Test event publishing

• Validate error handling

API Testing

• Test HTTP endpoints

• Verify response formats

• Test error scenarios

• Validate security

---

This REST Services documentation provides comprehensive guidance for implementing clean, maintainable, and scalable REST operations in FlexBase applications! 🚀