API Consumers (External Web Services)

Struktural handles external API communication by generating strongly-typed C# clients dynamically based on ExternalServiceDefinition JSON objects.

Importing via Studio

The easiest way to define a service is using the Studio. Navigate to the APIs module and click "Import OpenAPI / Swagger". By pasting a valid Swagger JSON/YAML file or providing a URL, Struktural will parse the endpoints, path parameters, and body DTO schemas automatically.

Promoting DTOs to Entities: Once imported, navigate to the Models (Data DTOs) tab of the service. Here you can view the external schemas parsed from the swagger file. If you wish to store this data permanently, click Promote to Entity. This will instantly generate a new Struktural Entity within your app-schema.json with the exact fields and types required by the external API.

API Service Editor

Authentication Strategies

External services often require authentication. The Auth property of the ExternalServiceDefinition handles this transparently so you do not need to manage tokens in your scripts.

"Auth": {
  "Type": "OAuth2_ClientCreds", 
  "CredentialsRef": { "Store": "PrimaryVault", "Key": "Stripe-OAuth-Json" }
}

Supported Auth Types:

None: Public API.
ApiKey: Injects a token into the Header or Query string based on the KeyLocation and KeyName settings.
Basic: Base64 encodes the credentials and injects an Authorization: Basic header.
OAuth2_ClientCreds: Implements the Machine-to-Machine flow. The vault secret MUST contain a JSON string with ClientId, ClientSecret, and TokenUrl. Struktural manages token fetching and caching automatically.
OAuth2_User: (Pass-through) Extracts the JWT Bearer token of the current logged-in user and forwards it to the external service.

Models (DTOs)

The Models array within the service definition defines the data shapes (Data Transfer Objects) expected by the external API. When the engine compiles, it creates native C# classes (e.g., Struktural.Generated.Services.Stripe.Models.ChargeDto) ensuring type safety in your scripts.