---
title: Resolve API client and route
summary: Resolves named API clients from the data portal and formats route templates for API-backed business objects.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Framework.Core
reference_type: package
operation_id: OP-CORE-008
trigger: Caller constructs API criteria or invokes GetApiClient or FormatRoute.
---

# Resolve API client and route

This operation is the non-SQL dispatch path used by `clsBusinessApiCriteriaBase`. It wires an API criteria object to the `IDataPortalInfo` client registry, guarantees routes are configured before first use, and formats route templates with call-site arguments so the REST layer has a fully resolved URL to execute against.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CORE-008 |
| **Trigger** | Caller constructs a `clsBusinessApiCriteriaBase` subclass or invokes `GetApiClient` / `FormatRoute`. |
| **Inputs** | `IDataPortalInfo`, API client key, optional controller name, route key, and route arguments. |
| **Outputs** | `IApiClient`, formatted `IApiRoute`, `Nothing`, or thrown `ArgumentException`. |
| **Primary components** | `clsBusinessApiCriteriaBase.New`, `clsBusinessApiCriteriaBase.GetApiClient`, `clsBusinessApiCriteriaBase.FormatRoute` |
| **Entry point** | `SAIF.Framework.Core\V1\Api\clsBusinessApiCriteriaBase.vb` |

## Steps

1. Construct the API criteria with a data portal.
   - The constructor stores `DataPortalInfo`.
   - It immediately calls `ConfigureRoutes()` so the derived criteria can populate `ApiRoutes` up front ([BR-004](../business-rules.md#br-004-api-criteria-sql-properties-are-always-empty-by-design)).
2. Resolve the named API client when `GetApiClient` is called.
   - The method reads `m_dataPortalInfo?.ApiClients.Item(key)` ([BR-004](../business-rules.md#br-004-api-criteria-sql-properties-are-always-empty-by-design)).
   - If the client is missing, it throws `ArgumentException` that names the missing key, optionally includes the controller, and shows how the caller should add the client to the DPI ([BR-004](../business-rules.md#br-004-api-criteria-sql-properties-are-always-empty-by-design)).
   - If the client exists, the method returns it unchanged.
3. Format a route template when `FormatRoute` is called.
   - The method looks up the route in `ApiRoutes` ([BR-004](../business-rules.md#br-004-api-criteria-sql-properties-are-always-empty-by-design)).
   - When the route exists, it applies `String.Format(route.Pattern, args)` and stores the rendered text in `route.Value`.
   - It returns the route object after formatting.
4. Handle missing routes without throwing.
   - If the route key is absent, `FormatRoute` returns `Nothing`, leaving the caller responsible for deciding how to proceed.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([API criteria created or used]) --> Routes[ConfigureRoutes]
	Routes --> Client[GetApiClient]
	Client --> Exists{Client exists?}
	Exists -->|No| EndErr([Throw ArgumentException])
	Exists -->|Yes| Route[FormatRoute]
	Route --> Found{Route exists?}
	Found -->|No| EndNil([Return Nothing])
	Found -->|Yes| EndOk([Return client and formatted route])
```

## Failure and edge-case behavior

- A missing API client fails fast with a descriptive `ArgumentException` naming the key that could not be resolved, rather than surfacing a generic null-reference failure later in the REST call.
- A missing route key does not throw — `FormatRoute` returns `Nothing` and leaves the caller responsible for deciding how to handle the gap, which differs from the fail-fast behavior of `GetApiClient`.
- The criteria base intentionally leaves all SQL properties empty by design, so callers on this path must stay on the API client/route mechanism rather than falling back to SQL execution ([BR-004](../business-rules.md#br-004-api-criteria-sql-properties-are-always-empty-by-design)).

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- SAIF.Framework.Core\V1\Api\clsBusinessApiCriteriaBase.vb