YamlHttpClient 2.1.1

YamlHttpClient

YAML config-based .NET HttpClient with retry, caching, chaos engineering, and multi-step orchestration.

Download from NuGet: https://www.nuget.org/packages/YamlHttpClient/

Table of contents

• Basic usage
• YAML config reference
• Loading config
• Dependency injection
• AutoCallAsync
• Retry
• Cache
• Chaos Monkey
• Mock
• Orchestrator
• Handlebars helpers
• Features checklist

Basic usage

var anyInputObject = new
{
 table = new[] { "v1", "v2" },
 date = new DateTime(2000, 1, 1),
 obj = new[] { new { test = 1 }, new { test = 2 } },
 val1 = new Dictionary<string, object>() { { "testkey", "testval" } },
 place = "urlPartDemo",
 System = new { CodeNT = "internalCode" }
};

// Load settings from a YAML file, targeting a named key
YamlHttpClientFactory httpClient = new YamlHttpClientFactory(
 new YamlHttpClientConfigBuilder().LoadFromFile("myYamlConfig.yml", "myHttpCall"));

// Build the HTTP message — placeholders are resolved from anyInputObject
var request = httpClient.BuildRequestMessage(anyInputObject);

// Optionally inspect the built content
var readContent = await request.Content.ReadAsStringAsync();

// Send
var response = await httpClient.SendAsync(request);

// Read response
var returnData = await response.Content.ReadAsStringAsync();

// Assert response matches check_response rules from config (throws if not)
await httpClient.CheckResponseAsync(response);

Or use the shorthand that combines build + send in one call:

var response = await httpClient.AutoCallAsync(anyInputObject);
await httpClient.CheckResponseAsync(response);

YAML config reference

http_client:
 myHttpCall:
 method: POST
 url: https://api.example.com/{{place}}/endpoint

 # NTLM auto-negotiation (app pool identity)
 use_default_credentials: true

 # HTTP Basic authentication
 # auth_basic: 'username:password'

 headers:
 CodeNT: '{{System.CodeNT}}'
 Accept: 'application/json'

 content:
 # JSON body with Handlebars templating
 json_content: |
 {
 "someVal": "{{val1}}",
 "flattenObj": {{{Json . ">flatten;_;_{0}" ">forcestring"}}}
 "obj": {{{Json .}}}
 }
 # Other content types (pick one):
 # string_content: 'raw text {{val}}'
 # form_content:
 # field1: value1
 # field2: '{{val}}'

 # Throws if the response body does not match expectations
 check_response:
 throw_exception_if_body_contains_any:
 - error
 throw_exception_if_body_not_contains_all:
 - success

 retry:
 max_retries: 3
 delay_milliseconds: 500
 retry_on_status_codes:
 - 500
 - 502
 - 503

 cache:
 enabled: true
 ttl_seconds: 120

 chaos:
 enabled: false
 injection_rate_percentage: 33
 delay_milliseconds: 200
 simulate_status_code: 503
 simulate_network_exception: false

 mock:
 enabled: false
 status_code: 200
 headers:
 Content-Type: 'application/json'
 body: '{ "result": "mocked" }'

Loading config

Three loaders are available on YamlHttpClientConfigBuilder:

// From a file path
var settings = new YamlHttpClientConfigBuilder().LoadFromFile("config.yml", "myHttpCall");

// From a YAML string (e.g. loaded from a database or environment variable)
var settings = new YamlHttpClientConfigBuilder().LoadFromString(yamlString, "myHttpCall");

// From a byte array (e.g. embedded resource)
var settings = new YamlHttpClientConfigBuilder().LoadFromBytes(yamlBytes, "myHttpCall");

var httpClient = new YamlHttpClientFactory(settings);

Dependency injection

// Startup / Program.cs
services.AddYamlHttpClientAccessor();

// In your service
public class MyService
{
 private readonly IYamlHttpClientAccessor _client;

 public MyService(IYamlHttpClientAccessor client)
 {
 _client = client;
 _client.HttpClientSettings = new YamlHttpClientConfigBuilder()
 .LoadFromFile("config.yml", "myHttpCall");
 _client.HandlebarsProvider = YamlHttpClientFactory.CreateDefaultHandleBars();
 }

 public async Task<string> CallAsync(object data)
 {
 var response = await _client.AutoCallAsync(data);
 await _client.CheckResponseAsync(response);
 return await response.Content.ReadAsStringAsync();
 }
}

AutoCallAsync

AutoCallAsync is a convenience method that wraps BuildRequestMessage + SendAsync(Func<HttpRequestMessage>) in a single call. It integrates with the retry and cache pipelines automatically.

// Without cancellation token
var response = await httpClient.AutoCallAsync(myData);

// With cancellation token
var response = await httpClient.AutoCallAsync(myData, cancellationToken);

Use AutoCallAsync instead of BuildRequestMessage + SendAsync whenever you want retry and cache to work together correctly — the factory-based overload of SendAsync is required for those features.

Retry

Retry is configured per HTTP client in YAML. The engine retries on specified HTTP status codes and on transient network exceptions (HttpRequestException, timeout).

http_client:
 myHttpCall:
 method: GET
 url: https://api.example.com/data
 retry:
 max_retries: 3 # Number of retries after the initial attempt
 delay_milliseconds: 500 # Wait between attempts
 retry_on_status_codes: # Only retry on these codes; omit to retry only on exceptions
 - 500
 - 502
 - 503
 - 504

var settings = new YamlHttpClientConfigBuilder().LoadFromString(yaml, "myHttpCall");
var httpClient = new YamlHttpClientFactory(settings);

// AutoCallAsync handles retries transparently
var response = await httpClient.AutoCallAsync(myData);

Cache

Responses are cached in memory keyed by Method + URL + body hash. Only successful responses (2xx) are cached. The cache is shared across all instances for the same URL.

http_client:
 myHttpCall:
 method: GET
 url: https://api.example.com/reference-data
 cache:
 enabled: true
 ttl_seconds: 600 # 10 minutes; default is 600

var settings = new YamlHttpClientConfigBuilder().LoadFromString(yaml, "myHttpCall");
var httpClient = new YamlHttpClientFactory(settings);

// First call hits the network; subsequent identical calls return from cache
var response = await httpClient.AutoCallAsync(myData);

Cache and retry work together: the cache is checked before the retry loop, and a successful retry response is stored in cache.

Chaos Monkey

Chaos Monkey injects failures into your HTTP calls at a configurable rate. This is useful for testing resilience locally or in a staging environment without needing an unstable external service.

http_client:
 myHttpCall:
 method: POST
 url: https://api.example.com/endpoint
 chaos:
 enabled: true
 injection_rate_percentage: 30 # 30% of calls will be affected
 delay_milliseconds: 300 # Always add 300ms delay (regardless of injection rate)
 simulate_status_code: 503 # Return a fake 503 on affected calls
 # simulate_network_exception: true # Throw HttpRequestException instead

The three chaos modes (combinable):

simulate_status_code and simulate_network_exception are only triggered when a call falls within the injection_rate_percentage. delay_milliseconds is always applied when set.

// Chaos is fully transparent to calling code — no changes needed
var response = await httpClient.AutoCallAsync(myData);

Combining chaos with retry lets you verify your retry policy actually recovers from failures:

http_client:
 myHttpCall:
 method: GET
 url: https://api.example.com/data
 chaos:
 enabled: true
 injection_rate_percentage: 50
 simulate_status_code: 503
 retry:
 max_retries: 3
 delay_milliseconds: 100
 retry_on_status_codes:
 - 503

Mock

Mock lets you return a predefined HTTP response directly from the YAML configuration, without making any real network call. This is useful during development, integration testing, or when an external API is not yet available.

http_client:
 myMockedCall:
 method: GET
 url: https://api.example.com/users
 mock:
 enabled: true
 status_code: 200
 headers:
 Content-Type: 'application/json'
 X-Custom-Header: 'mock-value'
 body: |
 {
 "users": [
 { "id": 1, "name": "Alice" },
 { "id": 2, "name": "Bob" }
 ]
 }

When mock.enabled is true, calling AutoCallAsync or SendAsync skips the HTTP call entirely and returns a fabricated HttpResponseMessage with the specified status code, headers, and body.

var settings = new YamlHttpClientConfigBuilder().LoadFromFile("config.yml", "myMockedCall");
var httpClient = new YamlHttpClientFactory(settings);

// No network call is made — the mock response is returned immediately
var response = await httpClient.AutoCallAsync(myData);
var content = await response.Content.ReadAsStringAsync();
// content = { "users": [ { "id": 1, "name": "Alice" }, ... ] }

Mock works seamlessly with check_response, so you can validate your mock responses against the same rules used in production:

http_client:
 myMockedCall:
 method: GET
 url: https://api.example.com/users
 mock:
 enabled: true
 status_code: 200
 body: '{ "status": "success", "data": [] }'
 check_response:
 throw_exception_if_body_not_contains_all:
 - success

Mock can also be combined with the orchestrator — individual steps in a pipeline can be mocked independently, which is useful when only some external APIs are available:

http_client_set:
 user_pipeline:
 sequence:
 - http_client: get_token
 - http_client: get_users

http_client:
 get_token:
 method: POST
 url: https://auth.example.com/token
 mock:
 enabled: true
 status_code: 200
 body: '{ "access_token": "fake-token-for-dev" }'

 get_users:
 method: GET
 url: https://api.example.com/users
 headers:
 Authorization: 'Bearer {{get_token.body.access_token}}'

Tip: Use mock to prototype your YAML pipelines before the real APIs are deployed. Once ready, simply set mock.enabled: false (or remove the mock block) to switch to live calls.

Orchestrator

YamlHttpOrchestrator (requires .NET 6+) executes named pipelines defined in http_client_set. Each pipeline runs an ordered sequence of HTTP calls; every step's response is aggregated and made available to subsequent steps and to the final data_adapter template via Handlebars.

YAML config

A single YAML file contains both http_client_set (the pipelines) and http_client (the individual client definitions). Each pipeline references its clients by name and defines its own data_adapter output template.

http_client_set:
 users:
 sequence:
 - http_client: get_token
 - http_client: get_users
 as: get_users # optional alias; defaults to http_client name
 data_adapter:
 template: |
 {
 "count": {{get_users.body.total}},
 "items": {{{Json get_users.body.records}}}
 }

 user_orders:
 sequence:
 - http_client: get_token
 - http_client: get_user
 - http_client: get_orders
 data_adapter:
 template: |
 {
 "customer": "{{get_user.body.name}}",
 "email": "{{get_user.body.email}}",
 "orders": {{{Json get_orders.body.records}}}
 }

http_client:
 get_token:
 method: POST
 url: https://auth.example.com/token
 content:
 json_content: |
 { "client_id": "{{input.clientId}}", "client_secret": "{{input.secret}}" }

 get_users:
 method: GET
 url: https://api.example.com/users
 headers:
 Authorization: 'Bearer {{get_token.body.access_token}}'
 Accept: 'application/json'
 retry:
 max_retries: 2
 delay_milliseconds: 500
 retry_on_status_codes: [500, 502, 503]
 chaos:
 enabled: false
 injection_rate_percentage: 50
 simulate_status_code: 500

 get_user:
 method: GET
 url: 'https://api.example.com/users/{{input.userId}}'
 headers:
 Authorization: 'Bearer {{get_token.body.access_token}}'
 Accept: 'application/json'

 get_orders:
 method: GET
 # References input data and a previous step's response
 url: 'https://api.example.com/orders?userId={{get_user.body.id}}'
 headers:
 Authorization: 'Bearer {{get_token.body.access_token}}'
 Accept: 'application/json'

If data_adapter.template is omitted or blank, ExecuteSetAsync returns the full aggregated data object as raw JSON.

Data model inside templates

After each step completes, its result is added to the aggregated data object under its alias (defaulting to the http_client name). The full shape available in any template is:

{
 input: { ...your inputData... },
 get_token: { body: {...}, headers: {...}, url: "https://..." },
 get_user: { body: {...}, headers: {...}, url: "https://..." },
 get_orders: { body: {...}, headers: {...}, url: "https://..." }
}

Both url fields in http_client definitions and data_adapter templates have full access to this object via Handlebars.

C# usage — ExecuteSetAsync

The preferred entry point. Loads the pipeline and all client definitions directly from the parsed config:

using YamlHttpClient;
using YamlHttpClient.Settings;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

// Parse the full YAML config (both http_client_set and http_client)
var yaml = File.ReadAllText("pipeline.yml");
var config = new DeserializerBuilder()
 .WithNamingConvention(NullNamingConvention.Instance)
 .IgnoreUnmatchedProperties()
 .Build()
 .Deserialize<YamlHttpClientConfigBuilder>(yaml);

var handlebars = YamlHttpClientFactory.CreateDefaultHandleBars();
var orchestrator = new YamlHttpOrchestrator(handlebars);

// Execute a named pipeline by key
var result = await orchestrator.ExecuteSetAsync(
 setName: "regions",
 config: config,
 inputData: new { clientId = "my-app", secret = "s3cr3t" },
 defaultHttpTimeout: TimeSpan.FromSeconds(30),
 ct: CancellationToken.None
);

Console.WriteLine(result);

// Inspect which URLs were actually called
foreach (var url in orchestrator.LastCalledUrls)
 Console.WriteLine($"Called: {url}");

C# usage — ExecuteSequenceAsync (advanced)

Use this overload when the sequence and data adapter template are defined in C# rather than in YAML:

var steps = new List<dynamic>
{
 new { HttpClient = "get_token", As = "get_token" },
 new { HttpClient = "get_regions", As = "get_regions" }
};

var result = await orchestrator.ExecuteSequenceAsync(
 inputData: new { clientId = "my-app", secret = "s3cr3t" },
 sequenceAppels: steps,
 dictClientsConfig: config.HttpClient,
 dataAdapterTemplate: "{{get_regions.body.result.records}}",
 defaultHttpTimeout: TimeSpan.FromSeconds(30),
 ct: CancellationToken.None
);

Default options

YamlHttpOrchestratorOptions provides fallback cache and retry settings applied to any step that does not define its own:

Pass null for options to use these defaults, or override selectively.

Handlebars helpers

All templates (URL, headers, body, data adapter) are processed with Handlebars.Net.

{{{Json VAR}}}

Serializes a variable to JSON.

{{{Json obj}}} → {"test":1}
{{{Json obj ">forcestring"}}} → "{\"test\":1}"
{{{Json val1 val2}}} → "concatenated strings"

{{{Json VAR ">flatten;SEP;IDX"}}}

Flattens a nested object to a single-level dictionary.

{{{Json . ">flatten;.;[{0}]"}}} → {"obj[0].test":1,"obj[1].test":2}
{{{Json . ">flatten;_;_{0}"}}} → {"obj_0_test":1,"obj_1_test":2}
{{{Json . ">flatten;_;_{0}" ">forcestring"}}} → {"obj_0_test":"1","obj_1_test":"2"}

{{#ifCond A OP B}}

Conditional block helper. Supported operators: =, ==, !=, <>, <, >, contains, in.

{{#ifCond status '=' 'active'}}Active{{else}}Inactive{{/ifCond}}
{{#ifCond roles 'contains' 'admin'}}Has admin{{/ifCond}}

{{{Base64 VAR}}}

Encodes an object or image to Base64.

{{{Base64 myObject}}}

Template caching

Templates are compiled once and cached automatically via CompileWithCache. Call HandleBarsExtensions.ClearTemplateCache() if you need to reload templates at runtime (e.g. hot reload of YAML config).

Features checklist

• ✅ All HTTP methods (GET, POST, PUT, DELETE, PATCH...)
• ✅ Any request headers with Handlebars templating
• ✅ JSON, string, form data and binary (Base64) content types
• ✅ Basic HTTP authentication
• ✅ NTLM authentication (app pool auto-negotiation)
• ✅ Response validation with configurable rules (check_response)
• ✅ Automatic retry with configurable status codes and delay
• ✅ In-memory response cache with TTL
• ✅ Chaos Monkey (delay, fake status code, network exception simulation)
• ✅ Mock responses (return predefined responses without network calls)
• ✅ Multi-step HTTP orchestration with data aggregation (YamlHttpOrchestrator, .NET 6+)
• ✅ Dependency injection support (IYamlHttpClientAccessor)
• ⬜ NTLM with explicit user/password
• ⬜ Client certificate authentication