Skip to main content

Migration from Core API v1 Documentation

This guide helps you transition from the old "Core Platform API" documentation to the new "Core Api Platform v4" documentation.

Overview​

The Core Api Platform v4 documentation is a complete rewrite based on code analysis, providing:

  • 87 comprehensive pages covering all features
  • 3 new major features previously undocumented
  • Enhanced examples with real request/response data
  • Better organization with progressive disclosure
  • Complete API reference with error codes and endpoints

Documentation Mapping​

Old → New Page Mappings​

Old LocationNew LocationNotes
/core-api/authentication/core-api-platform-v4/security/authenticationEnhanced with 3-phase flow, sessionId, token validator
/core-api/core-components/validation-rules/core-api-platform-v4/write-patterns/validationEnhanced with COD_UTENTE, AC/VARS validation
/core-api/core-components/http-request-composition/core-api-platform-v4/reference/api-endpointsEnhanced with custom headers
/core-api/core-components/query-data/core-api-platform-v4/query-patterns/Split into multiple focused pages
/core-api/core-components/query-documents/core-api-platform-v4/query-patterns/document-queriesComplete rewrite with examples

Topic to New Location Mapping​

TopicNew Location
Core Concepts
Dimensions/core-api-platform-v4/core-concepts/dimensions
MAP Framework/core-api-platform-v4/core-concepts/map-framework
Context Chain/core-api-platform-v4/core-concepts/context-chain
COD_ON_OFF/core-api-platform-v4/core-concepts/field-visibility
TREC Lifecycle/core-api-platform-v4/core-concepts/entity-lifecycle
Source Parameter/core-api-platform-v4/core-concepts/source-parameter ⭐ NEW
Query Patterns
Basic Filtering/core-api-platform-v4/query-patterns/filtering
Field Retrieval/core-api-platform-v4/query-patterns/field-retrieval
Pagination/core-api-platform-v4/query-patterns/pagination
Document API/core-api-platform-v4/query-patterns/document-queries ⭐ NEW
AC/VARS Queries/core-api-platform-v4/query-patterns/ac-vars-queries ⭐ NEW
Write Operations
Create Operations/core-api-platform-v4/write-patterns/create-operations
Update Operations/core-api-platform-v4/write-patterns/update-operations
Delete Operations/core-api-platform-v4/write-patterns/delete-operations
Validation/core-api-platform-v4/write-patterns/validation
Security
Authentication/core-api-platform-v4/security/authentication
Authorization/core-api-platform-v4/security/authorization
Grant System/core-api-platform-v4/security/grant-system
Reference
API Endpoints/core-api-platform-v4/reference/api-endpoints
Error Codes/core-api-platform-v4/reference/error-codes
Metadata Tables/core-api-platform-v4/reference/metadata-tables

New Features in v2​

1. Document API (Previously Undocumented) ⭐​

Location: /core-api-platform-v4/query-patterns/document-queries

Advanced multi-table aggregation query system with pre-defined and on-the-fly documents.

Example:

# Pre-defined document
GET /api/v4/document/SHORT_ARTICLE_INFO/055570?codLst=1&areaListino=ITA

# On-the-fly document
POST /api/v4/document
{
  "dim": "ART",
  "val_key": "055570",
  "related_dim": {
    "BCODE": ["XBCODE03"],
    "LST": ["XLST10", "XLST13"]
  },
  "compact": true
}

2. AC/VARS Query Endpoint (Previously Undocumented) ⭐​

Location: /core-api-platform-v4/query-patterns/ac-vars-queries

Dedicated endpoint for querying foreign key field values (autocomplete and select lists).

Example:

# VARS query (full list)
GET /api/v4/core/vars?source=settings-2&field=XART11

# AC query (filtered)
GET /api/v4/core/vars?source=settings-2&field=XART11&$filter=startwith(XCL104,'Magl')

# AC query (bypass filter)
GET /api/v4/core/vars?source=settings-2&field=XART11&getACList=1

3. Source Parameter Concept (Previously Undocumented) ⭐​

Location: /core-api-platform-v4/core-concepts/source-parameter

Critical business logic identifier required in all API calls, linking TB_MENU to dimensions.

Example:

# Format: {microservice}-{number}
GET /api/v4/core/ART?source=settings-2

POST /api/v4/core/ART
{
  "source": "settings-2",
  "XART20": "Product Name"
}

4. Enhanced Query Parameters​

Location: /core-api-platform-v4/query-patterns/field-retrieval

New query parameters documented:

  • forceListCost - Bypass COD_ON_OFF rules
  • $group - SQL GROUP BY operations
  • debug - Return generated SQL query
  • cond_trec - Special TREC filtering

Example:

# Force specific fields (ignore COD_ON_OFF)
GET /api/v4/core/ART?source=settings-2&forceListCost=XART20,XART25

# Debug SQL query
GET /api/v4/core/ART?source=settings-2&debug=true

# Custom TREC filtering
GET /api/v4/core/ART?source=settings-2&cond_trec=C,P

5. Enhanced Authentication Details​

Location: /core-api-platform-v4/security/authentication

New details documented:

  • 3-phase authentication process (Authentication → Profiling → Interface Accessibility)
  • JWT lifecycle: 15 minutes active + 60 minutes renewable
  • sessionId concept and TB_ANAG_SESSIONS00 structure
  • Token validator endpoint /api/v4/auth/tokenvalidator
  • Access token authentication alternative

6. Custom HTTP Headers​

Location: /core-api-platform-v4/reference/api-endpoints

Documented custom headers for routing:

  • canary-mode: on - Use canary deployment
  • developer: {name} - Use developer's Skaffold instance
  • microservice: {name} - Specify microservice for routing

7. Enhanced Error Handling​

Location: /core-api-platform-v4/reference/error-codes

  • Nested error response format for multi-microservice calls
  • DELETE returns 205 Reset Content (not 204)
  • Complete error code catalog

Breaking Changes​

None. The v2 documentation describes the same API with no breaking changes. All existing API calls continue to work as before.

Migration Checklist​

For Developers​

  • Bookmark new documentation root: /core-api-platform-v4/
  • Read 13 core concepts: /core-api-platform-v4/core-concepts/
  • Update internal wikis/documentation with new URLs
  • Use Document API for complex multi-table queries
  • Use AC/VARS endpoint for foreign key lookups
  • Ensure source parameter is included in all calls
  • Use enhanced query parameters (forceListCost, $group, debug, cond_trec)

For Architects​

  • Review new core concepts section
  • Understand source parameter and TB_MENU binding
  • Review Document API for data aggregation use cases
  • Update training materials with new documentation
  • Plan migration of legacy integrations to use new features

For Teams​

  • Conduct training session on 13 core concepts
  • Update code examples to use new query parameters
  • Adopt Document API for complex reporting needs
  • Standardize on AC/VARS endpoint for foreign key queries
  • Update error handling for nested error responses

Before/After Examples​

Example 1: Complex Query with Multiple Parameters​

Before (v1 docs - limited guidance):

GET /api/v4/core/ART?$filter=XART06 eq true

After (v2 docs - comprehensive parameters):

GET /api/v4/core/ART?source=settings-2&\
  center_dett=visualizza&\
  $filter=XART06 eq true AND XART01 eq 2&\
  $select=ART_ID,XART20,XART25&\
  $order=XART20 ASC&\
  $num_rows=25&\
  $offset=0&\
  cond_trec=C

Example 2: Foreign Key Lookup​

Before (v1 docs - not documented):

# No specific endpoint documented
# Developers queried dimension directly
GET /api/v4/core/DEPFOOD?source=settings-2

After (v2 docs - dedicated endpoint):

# Use AC/VARS endpoint
GET /api/v4/core/vars?source=settings-2&field=XART53

Example 3: Multi-Table Aggregation​

Before (v1 docs - basic join examples):

# Multiple API calls required
GET /api/v4/core/ART/055570?source=settings-2
GET /api/v4/core/BCODE?source=settings-2&filter[XBCODE51]=055570
GET /api/v4/core/LST?source=settings-2&filter[XLST51]=055570

After (v2 docs - Document API):

# Single API call with pre-defined document
GET /api/v4/document/FULL_ARTICLE_INFO/055570?codLst=1&areaListino=ITA

Where to Start​

Recommended Learning Path:

  1. Start with Core Concepts → /core-api-platform-v4/core-concepts/

    • Read all 13 concepts (2-3 hours)
    • Focus on Source Parameter, Context Chain, COD_ON_OFF

  2. Learn Query Patterns → /core-api-platform-v4/query-patterns/

    • Document API for complex queries
    • AC/VARS endpoint for foreign keys
    • Advanced filtering with cond_trec

  3. Review Write Patterns → /core-api-platform-v4/write-patterns/

    • Enhanced validation documentation
    • COD_UTENTE weight-based access

  4. Understand Security → /core-api-platform-v4/security/

    • 3-phase authentication flow
    • sessionId and token lifecycle

  5. Reference Materials → /core-api-platform-v4/reference/

    • Complete API endpoint catalog
    • Error code reference
    • Metadata table schemas

Getting Help​

  • Questions? Check the comprehensive examples in each section
  • Issues? Review error codes reference at /core-api-platform-v4/reference/error-codes
  • Best Practices? See /core-api-platform-v4/best-practices/

Feedback​

The new documentation is continuously improved. If you find gaps or errors, please report them to the documentation team.

Last Updated: December 2025 Documentation Version: Core Api Platform v4 (87 pages, ~112,000 words)