Took Me a Few Days to Get This Right: The Integration Gauntlet (SAP Build & Destinations)

2026-06-17 · Source: Towards AI - Medium · Field: Technology & Digital — Software Development & Engineering, Artificial Intelligence & Machine Learning, Cloud Computing & IT Infrastructure · Depth: Intermediate, medium

Summary

Integrating a custom FastAPI backend API with SAP Build Actions presents several significant challenges, as detailed in this article. The primary hurdle involves an OpenAPI version mismatch, where FastAPI's 3.1 specification is incompatible with SAP Build Actions' requirement for OpenAPI 3.0.x. This necessitates manual or automated conversion of the specification, including changing the version, adjusting "anyOf" and "nullable" structures, and adding an explicit "servers" section. Furthermore, SAP Build Actions imposes a hard limit of 20 actions per imported specification, forcing developers to consolidate API endpoints by exposing capabilities rather than numerous individual resources. A critical architectural distinction is SAP's handling of authentication, which is delegated to a separate BTP Destination layer, centralizing URL, authentication, and connectivity settings. The author stresses the importance of isolated testing for each layer—API, Destination, Action, Skill, and Agent—to effectively debug issues that often manifest in one layer but originate in another.

Key takeaway

For AI Engineers integrating custom APIs into SAP Build, anticipate specific platform constraints that demand early architectural adjustments. You must account for OpenAPI 3.0.x compatibility by automating specification downgrades and consolidate API endpoints to stay within the 20 Action limit. Crucially, configure authentication via BTP Destinations, not within Actions, and adopt a rigorous isolated testing strategy for each layer—API, Destination, Action, Skill, and Agent—to prevent complex debugging later.

Key insights

Integrating custom APIs with SAP Build requires navigating specific OpenAPI versioning, action limits, and a centralized authentication model.

Principles

• API design for AI agents benefits from capability consolidation.
• Centralized connectivity (Destinations) enhances enterprise governance.
• Isolated layer testing is crucial for effective debugging.

Method

The integration workflow involves exporting OpenAPI 3.1, converting it to 3.0.3, uploading to SAP Build Actions, reviewing, and individually testing each generated Action before proceeding to Skills.

In practice

• Automate OpenAPI specification conversion for version compatibility.
• Consolidate API endpoints to manage SAP Build's 20 Action limit.
• Configure BTP Destinations for centralized API authentication.

Topics

• SAP Build Actions
• BTP Destinations
• OpenAPI Specification
• API Integration
• FastAPI
• AI Agent Development

Best for: AI Engineer, Software Engineer, AI Architect

Related on AIssential

• Building a Custom AI Agent with SAP Joule Studio: The Complete Guide Nobody Wrote — Integrating custom REST APIs with SAP Joule Studio requires specific architectural patterns and workarounds for undocumented limitations.
• SAP user group slams 'uncertainty' in ERP giant's API policy — Unclear API policies can hinder innovation and adoption of new technologies like AI within enterprise ecosystems.
• NTT Data Expands Agentic Footprint With WinWire Acquisition — Strategic acquisitions of specialized cloud and AI engineering firms can bridge the gap between AI experimentation and enterprise-wide deployment.
• How to Deploy MCP Servers as an API Endpoint — Clarifai provides an end-to-end AI platform with modules, industry solutions, and use-case specific applications.
• The Backend Skills That Still Matter When AI Writes Half Your Code — AI-generated code often misses real-world complexities like idempotency, highlighting critical gaps in system resilience.
• Consolidating systems for AI with iPaaS — Fragmented IT landscapes hinder AI adoption and business outcomes, necessitating consolidated integration platforms.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Towards AI - Medium.