bc-code-intelligence-mcp 1.3.4 → 1.3.6

package/embedded-knowledge/domains/alex-architect/samples/api-interface-design.md

@@ -0,0 +1,565 @@
+# API Interface Design Patterns - AL Code Examples
+
+This sample demonstrates effective API interface design patterns for maintainable, extensible APIs in Business Central.
+
+## Basic Interface Design Patterns
+
+```al
+// Clean, focused interface for customer operations
+interface ICustomerService
+{
+    procedure CreateCustomer(CustomerData: Dictionary of [Text, Variant]): Code[20];
+    procedure UpdateCustomer(CustomerNo: Code[20]; UpdateData: Dictionary of [Text, Variant]): Boolean;
+    procedure GetCustomer(CustomerNo: Code[20]): Dictionary of [Text, Variant];
+    procedure DeleteCustomer(CustomerNo: Code[20]): Boolean;
+}
+
+// Separate interface for customer queries (Command-Query Separation)
+interface ICustomerQuery
+{
+    procedure FindCustomersByName(NamePattern: Text): List of [Code[20]];
+    procedure GetCustomerSalesHistory(CustomerNo: Code[20]; FromDate: Date; ToDate: Date): List of [Dictionary of [Text, Variant]];
+    procedure GetCustomerBalance(CustomerNo: Code[20]): Decimal;
+    procedure ValidateCustomerExists(CustomerNo: Code[20]): Boolean;
+}
+```
+
+## Fluent Interface Pattern
+
+```al
+// Fluent interface for sales order creation
+interface ISalesOrderBuilder
+{
+    procedure ForCustomer(CustomerNo: Code[20]): Interface ISalesOrderBuilder;
+    procedure WithOrderDate(OrderDate: Date): Interface ISalesOrderBuilder;
+    procedure AddItem(ItemNo: Code[20]; Quantity: Decimal): Interface ISalesOrderBuilder;
+    procedure AddItemWithPrice(ItemNo: Code[20]; Quantity: Decimal; UnitPrice: Decimal): Interface ISalesOrderBuilder;
+    procedure WithShipToAddress(Address: Dictionary of [Text, Variant]): Interface ISalesOrderBuilder;
+    procedure WithPaymentTerms(PaymentTermsCode: Code[10]): Interface ISalesOrderBuilder;
+    procedure Build(): Code[20];
+}
+
+// Implementation of fluent interface
+codeunit 50600 "Sales Order Builder" implements ISalesOrderBuilder
+{
+    var
+        CustomerNo: Code[20];
+        OrderDate: Date;
+        Items: List of [Dictionary of [Text, Variant]];
+        ShipToAddress: Dictionary of [Text, Variant];
+        PaymentTermsCode: Code[10];
+
+    procedure ForCustomer(NewCustomerNo: Code[20]): Interface ISalesOrderBuilder
+    begin
+        CustomerNo := NewCustomerNo;
+        exit(this);
+    end;
+
+    procedure WithOrderDate(NewOrderDate: Date): Interface ISalesOrderBuilder
+    begin
+        OrderDate := NewOrderDate;
+        exit(this);
+    end;
+
+    procedure AddItem(ItemNo: Code[20]; Quantity: Decimal): Interface ISalesOrderBuilder
+    var
+        ItemData: Dictionary of [Text, Variant];
+    begin
+        ItemData.Set('ItemNo', ItemNo);
+        ItemData.Set('Quantity', Quantity);
+        Items.Add(ItemData);
+        exit(this);
+    end;
+
+    procedure AddItemWithPrice(ItemNo: Code[20]; Quantity: Decimal; UnitPrice: Decimal): Interface ISalesOrderBuilder
+    var
+        ItemData: Dictionary of [Text, Variant];
+    begin
+        ItemData.Set('ItemNo', ItemNo);
+        ItemData.Set('Quantity', Quantity);
+        ItemData.Set('UnitPrice', UnitPrice);
+        Items.Add(ItemData);
+        exit(this);
+    end;
+
+    procedure WithShipToAddress(Address: Dictionary of [Text, Variant]): Interface ISalesOrderBuilder
+    begin
+        ShipToAddress := Address;
+        exit(this);
+    end;
+
+    procedure WithPaymentTerms(NewPaymentTermsCode: Code[10]): Interface ISalesOrderBuilder
+    begin
+        PaymentTermsCode := NewPaymentTermsCode;
+        exit(this);
+    end;
+
+    procedure Build(): Code[20]
+    var
+        SalesHeader: Record "Sales Header";
+        SalesLine: Record "Sales Line";
+        ItemData: Dictionary of [Text, Variant];
+        LineNo: Integer;
+    begin
+        if CustomerNo = '' then
+            Error('Customer number is required');
+
+        // Create sales header
+        SalesHeader.Init();
+        SalesHeader."Document Type" := SalesHeader."Document Type"::Order;
+        SalesHeader."No." := '';
+        SalesHeader.Insert(true);
+
+        SalesHeader.Validate("Sell-to Customer No.", CustomerNo);
+
+        if OrderDate <> 0D then
+            SalesHeader.Validate("Order Date", OrderDate);
+
+        if PaymentTermsCode <> '' then
+            SalesHeader.Validate("Payment Terms Code", PaymentTermsCode);
+
+        SalesHeader.Modify(true);
+
+        // Add ship-to address if specified
+        if ShipToAddress.Count > 0 then
+            ApplyShipToAddress(SalesHeader, ShipToAddress);
+
+        // Add items
+        LineNo := 10000;
+        foreach ItemData in Items do begin
+            CreateSalesLine(SalesHeader, ItemData, LineNo);
+            LineNo += 10000;
+        end;
+
+        exit(SalesHeader."No.");
+    end;
+
+    local procedure ApplyShipToAddress(var SalesHeader: Record "Sales Header"; Address: Dictionary of [Text, Variant])
+    var
+        ShipToName: Text[100];
+        ShipToAddress1: Text[100];
+        ShipToCity: Text[30];
+    begin
+        if Address.Get('Name', ShipToName) then
+            SalesHeader.Validate("Ship-to Name", ShipToName);
+
+        if Address.Get('Address', ShipToAddress1) then
+            SalesHeader.Validate("Ship-to Address", ShipToAddress1);
+
+        if Address.Get('City', ShipToCity) then
+            SalesHeader.Validate("Ship-to City", ShipToCity);
+
+        SalesHeader.Modify(true);
+    end;
+
+    local procedure CreateSalesLine(SalesHeader: Record "Sales Header"; ItemData: Dictionary of [Text, Variant]; LineNo: Integer)
+    var
+        SalesLine: Record "Sales Line";
+        ItemNo: Code[20];
+        Quantity: Decimal;
+        UnitPrice: Decimal;
+    begin
+        SalesLine.Init();
+        SalesLine."Document Type" := SalesHeader."Document Type";
+        SalesLine."Document No." := SalesHeader."No.";
+        SalesLine."Line No." := LineNo;
+        SalesLine.Insert(true);
+
+        if ItemData.Get('ItemNo', ItemNo) then
+            SalesLine.Validate("No.", ItemNo);
+
+        if ItemData.Get('Quantity', Quantity) then
+            SalesLine.Validate(Quantity, Quantity);
+
+        if ItemData.Get('UnitPrice', UnitPrice) then
+            SalesLine.Validate("Unit Price", UnitPrice);
+
+        SalesLine.Modify(true);
+    end;
+}
+```
+
+## Result Pattern for Error Handling
+
+```al
+// Result pattern for robust error handling
+interface IOperationResult
+{
+    procedure IsSuccess(): Boolean;
+    procedure IsFailure(): Boolean;
+    procedure GetErrorMessage(): Text;
+    procedure GetErrorCode(): Text[20];
+    procedure GetData(): Dictionary of [Text, Variant];
+}
+
+// Implementation of operation result
+codeunit 50601 "Operation Result" implements IOperationResult
+{
+    var
+        Success: Boolean;
+        ErrorMessage: Text;
+        ErrorCode: Text[20];
+        Data: Dictionary of [Text, Variant];
+
+    procedure Initialize(IsSuccessful: Boolean; Message: Text; Code: Text[20]; ResultData: Dictionary of [Text, Variant])
+    begin
+        Success := IsSuccessful;
+        ErrorMessage := Message;
+        ErrorCode := Code;
+        Data := ResultData;
+    end;
+
+    procedure IsSuccess(): Boolean
+    begin
+        exit(Success);
+    end;
+
+    procedure IsFailure(): Boolean
+    begin
+        exit(not Success);
+    end;
+
+    procedure GetErrorMessage(): Text
+    begin
+        exit(ErrorMessage);
+    end;
+
+    procedure GetErrorCode(): Text[20]
+    begin
+        exit(ErrorCode);
+    end;
+
+    procedure GetData(): Dictionary of [Text, Variant]
+    begin
+        exit(Data);
+    end;
+
+    procedure CreateSuccess(ResultData: Dictionary of [Text, Variant]): Interface IOperationResult
+    var
+        Result: Codeunit "Operation Result";
+    begin
+        Result.Initialize(true, '', '', ResultData);
+        exit(Result);
+    end;
+
+    procedure CreateFailure(Message: Text; Code: Text[20]): Interface IOperationResult
+    var
+        Result: Codeunit "Operation Result";
+        EmptyData: Dictionary of [Text, Variant];
+    begin
+        Result.Initialize(false, Message, Code, EmptyData);
+        exit(Result);
+    end;
+}
+```
+
+## Service Interface with Result Pattern
+
+```al
+// Enhanced customer service using result pattern
+interface IAdvancedCustomerService
+{
+    procedure CreateCustomer(CustomerData: Dictionary of [Text, Variant]): Interface IOperationResult;
+    procedure UpdateCustomer(CustomerNo: Code[20]; UpdateData: Dictionary of [Text, Variant]): Interface IOperationResult;
+    procedure GetCustomer(CustomerNo: Code[20]): Interface IOperationResult;
+    procedure ValidateCustomerData(CustomerData: Dictionary of [Text, Variant]): Interface IOperationResult;
+}
+
+// Implementation with comprehensive error handling
+codeunit 50602 "Advanced Customer Service" implements IAdvancedCustomerService
+{
+    procedure CreateCustomer(CustomerData: Dictionary of [Text, Variant]): Interface IOperationResult
+    var
+        Customer: Record Customer;
+        ValidationResult: Interface IOperationResult;
+        CustomerNo: Code[20];
+        ResultData: Dictionary of [Text, Variant];
+        OperationResult: Codeunit "Operation Result";
+    begin
+        // Validate input data
+        ValidationResult := ValidateCustomerData(CustomerData);
+        if ValidationResult.IsFailure() then
+            exit(ValidationResult);
+
+        try
+            // Create customer
+            Customer.Init();
+            Customer."No." := '';
+            Customer.Insert(true);
+            CustomerNo := Customer."No.";
+
+            // Apply data
+            ApplyCustomerData(Customer, CustomerData);
+
+            // Prepare success result
+            ResultData.Set('CustomerNo', CustomerNo);
+            ResultData.Set('Created', true);
+
+            exit(OperationResult.CreateSuccess(ResultData));
+
+        except
+            exit(OperationResult.CreateFailure(GetLastErrorText(), 'CREATE_FAILED'));
+        end;
+    end;
+
+    procedure UpdateCustomer(CustomerNo: Code[20]; UpdateData: Dictionary of [Text, Variant]): Interface IOperationResult
+    var
+        Customer: Record Customer;
+        ValidationResult: Interface IOperationResult;
+        ResultData: Dictionary of [Text, Variant];
+        OperationResult: Codeunit "Operation Result";
+    begin
+        if not Customer.Get(CustomerNo) then
+            exit(OperationResult.CreateFailure(StrSubstNo('Customer %1 not found', CustomerNo), 'NOT_FOUND'));
+
+        // Validate update data
+        ValidationResult := ValidateCustomerData(UpdateData);
+        if ValidationResult.IsFailure() then
+            exit(ValidationResult);
+
+        try
+            ApplyCustomerData(Customer, UpdateData);
+
+            ResultData.Set('CustomerNo', CustomerNo);
+            ResultData.Set('Updated', true);
+
+            exit(OperationResult.CreateSuccess(ResultData));
+
+        except
+            exit(OperationResult.CreateFailure(GetLastErrorText(), 'UPDATE_FAILED'));
+        end;
+    end;
+
+    procedure GetCustomer(CustomerNo: Code[20]): Interface IOperationResult
+    var
+        Customer: Record Customer;
+        CustomerData: Dictionary of [Text, Variant];
+        OperationResult: Codeunit "Operation Result";
+    begin
+        if not Customer.Get(CustomerNo) then
+            exit(OperationResult.CreateFailure(StrSubstNo('Customer %1 not found', CustomerNo), 'NOT_FOUND'));
+
+        CustomerData := ExtractCustomerData(Customer);
+        exit(OperationResult.CreateSuccess(CustomerData));
+    end;
+
+    procedure ValidateCustomerData(CustomerData: Dictionary of [Text, Variant]): Interface IOperationResult
+    var
+        CustomerName: Text[100];
+        ValidationErrors: List of [Text];
+        ErrorMessage: Text;
+        OperationResult: Codeunit "Operation Result";
+        ResultData: Dictionary of [Text, Variant];
+    begin
+        // Validate required fields
+        if not CustomerData.Get('Name', CustomerName) or (CustomerName = '') then
+            ValidationErrors.Add('Customer name is required');
+
+        if CustomerName <> '' then begin
+            if StrLen(CustomerName) > 100 then
+                ValidationErrors.Add('Customer name cannot exceed 100 characters');
+        end;
+
+        // Additional validation logic...
+
+        if ValidationErrors.Count > 0 then begin
+            ErrorMessage := JoinErrors(ValidationErrors);
+            exit(OperationResult.CreateFailure(ErrorMessage, 'VALIDATION_FAILED'));
+        end;
+
+        ResultData.Set('Valid', true);
+        exit(OperationResult.CreateSuccess(ResultData));
+    end;
+
+    local procedure ApplyCustomerData(var Customer: Record Customer; CustomerData: Dictionary of [Text, Variant])
+    var
+        CustomerName: Text[100];
+        Address: Text[100];
+        City: Text[30];
+        PhoneNo: Text[30];
+        Email: Text[80];
+    begin
+        if CustomerData.Get('Name', CustomerName) then
+            Customer.Validate(Name, CustomerName);
+
+        if CustomerData.Get('Address', Address) then
+            Customer.Validate(Address, Address);
+
+        if CustomerData.Get('City', City) then
+            Customer.Validate(City, City);
+
+        if CustomerData.Get('PhoneNo', PhoneNo) then
+            Customer.Validate("Phone No.", PhoneNo);
+
+        if CustomerData.Get('Email', Email) then
+            Customer.Validate("E-Mail", Email);
+
+        Customer.Modify(true);
+    end;
+
+    local procedure ExtractCustomerData(Customer: Record Customer): Dictionary of [Text, Variant]
+    var
+        CustomerData: Dictionary of [Text, Variant];
+    begin
+        CustomerData.Set('CustomerNo', Customer."No.");
+        CustomerData.Set('Name', Customer.Name);
+        CustomerData.Set('Address', Customer.Address);
+        CustomerData.Set('City', Customer.City);
+        CustomerData.Set('PostCode', Customer."Post Code");
+        CustomerData.Set('PhoneNo', Customer."Phone No.");
+        CustomerData.Set('Email', Customer."E-Mail");
+        CustomerData.Set('CreditLimit', Customer."Credit Limit (LCY)");
+        CustomerData.Set('Blocked', Customer.Blocked);
+
+        exit(CustomerData);
+    end;
+
+    local procedure JoinErrors(Errors: List of [Text]): Text
+    var
+        ErrorMessage: Text;
+        Error: Text;
+    begin
+        foreach Error in Errors do begin
+            if ErrorMessage <> '' then
+                ErrorMessage += '; ';
+            ErrorMessage += Error;
+        end;
+
+        exit(ErrorMessage);
+    end;
+}
+```
+
+## Versioned Interface Pattern
+
+```al
+// Interface versioning for backward compatibility
+interface ICustomerServiceV1
+{
+    procedure CreateCustomer(Name: Text[100]; Address: Text[100]): Code[20];
+    procedure GetCustomerName(CustomerNo: Code[20]): Text[100];
+}
+
+interface ICustomerServiceV2 extends ICustomerServiceV1
+{
+    procedure CreateCustomerAdvanced(CustomerData: Dictionary of [Text, Variant]): Interface IOperationResult;
+    procedure GetCustomerDetails(CustomerNo: Code[20]): Dictionary of [Text, Variant];
+    procedure UpdateCustomer(CustomerNo: Code[20]; UpdateData: Dictionary of [Text, Variant]): Interface IOperationResult;
+}
+
+// Implementation supporting both versions
+codeunit 50603 "Customer Service V2" implements ICustomerServiceV2
+{
+    // V1 methods for backward compatibility
+    procedure CreateCustomer(Name: Text[100]; Address: Text[100]): Code[20]
+    var
+        CustomerData: Dictionary of [Text, Variant];
+        Result: Interface IOperationResult;
+        CustomerNo: Code[20];
+    begin
+        CustomerData.Set('Name', Name);
+        CustomerData.Set('Address', Address);
+
+        Result := CreateCustomerAdvanced(CustomerData);
+        if Result.IsSuccess() then begin
+            Result.GetData().Get('CustomerNo', CustomerNo);
+            exit(CustomerNo);
+        end else begin
+            Error(Result.GetErrorMessage());
+        end;
+    end;
+
+    procedure GetCustomerName(CustomerNo: Code[20]): Text[100]
+    var
+        CustomerDetails: Dictionary of [Text, Variant];
+        CustomerName: Text[100];
+    begin
+        CustomerDetails := GetCustomerDetails(CustomerNo);
+        if CustomerDetails.Get('Name', CustomerName) then
+            exit(CustomerName);
+
+        exit('');
+    end;
+
+    // V2 methods with enhanced functionality
+    procedure CreateCustomerAdvanced(CustomerData: Dictionary of [Text, Variant]): Interface IOperationResult
+    var
+        AdvancedService: Codeunit "Advanced Customer Service";
+    begin
+        exit(AdvancedService.CreateCustomer(CustomerData));
+    end;
+
+    procedure GetCustomerDetails(CustomerNo: Code[20]): Dictionary of [Text, Variant]
+    var
+        AdvancedService: Codeunit "Advanced Customer Service";
+        Result: Interface IOperationResult;
+        EmptyData: Dictionary of [Text, Variant];
+    begin
+        Result := AdvancedService.GetCustomer(CustomerNo);
+        if Result.IsSuccess() then
+            exit(Result.GetData())
+        else
+            exit(EmptyData);
+    end;
+
+    procedure UpdateCustomer(CustomerNo: Code[20]; UpdateData: Dictionary of [Text, Variant]): Interface IOperationResult
+    var
+        AdvancedService: Codeunit "Advanced Customer Service";
+    begin
+        exit(AdvancedService.UpdateCustomer(CustomerNo, UpdateData));
+    end;
+}
+```
+
+## Usage Example
+
+```al
+// Example of using the designed interfaces
+codeunit 50604 "API Usage Example"
+{
+    procedure DemonstrateAPIUsage()
+    var
+        SalesOrderBuilder: Codeunit "Sales Order Builder";
+        CustomerService: Codeunit "Advanced Customer Service";
+        CustomerData: Dictionary of [Text, Variant];
+        ShipToAddress: Dictionary of [Text, Variant];
+        Result: Interface IOperationResult;
+        OrderNo: Code[20];
+        CustomerNo: Code[20];
+    begin
+        // Create customer using advanced service
+        CustomerData.Set('Name', 'Example Customer');
+        CustomerData.Set('Address', '123 Main Street');
+        CustomerData.Set('City', 'Example City');
+        CustomerData.Set('PhoneNo', '555-0123');
+        CustomerData.Set('Email', 'customer@example.com');
+
+        Result := CustomerService.CreateCustomer(CustomerData);
+
+        if Result.IsFailure() then begin
+            Message('Customer creation failed: %1', Result.GetErrorMessage());
+            exit;
+        end;
+
+        Result.GetData().Get('CustomerNo', CustomerNo);
+
+        // Create sales order using fluent interface
+        ShipToAddress.Set('Name', 'Shipping Department');
+        ShipToAddress.Set('Address', '456 Shipping Lane');
+        ShipToAddress.Set('City', 'Warehouse City');
+
+        OrderNo := SalesOrderBuilder
+            .ForCustomer(CustomerNo)
+            .WithOrderDate(Today)
+            .AddItem('ITEM001', 5)
+            .AddItemWithPrice('ITEM002', 10, 25.50)
+            .WithShipToAddress(ShipToAddress)
+            .WithPaymentTerms('30 DAYS')
+            .Build();
+
+        Message('Sales order %1 created successfully for customer %2', OrderNo, CustomerNo);
+    end;
+}
+```
+
+This comprehensive example demonstrates clean API interface design with separation of concerns, fluent interfaces, robust error handling using the result pattern, and interface versioning for backward compatibility.