Skip to content

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.
  2. The constructor stores DataPortalInfo.
  3. It immediately calls ConfigureRoutes() so the derived criteria can populate ApiRoutes up front (BR-004).
  4. Resolve the named API client when GetApiClient is called.
  5. The method reads m_dataPortalInfo?.ApiClients.Item(key) (BR-004).
  6. 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).
  7. If the client exists, the method returns it unchanged.
  8. Format a route template when FormatRoute is called.
  9. The method looks up the route in ApiRoutes (BR-004).
  10. When the route exists, it applies String.Format(route.Pattern, args) and stores the rendered text in route.Value.
  11. It returns the route object after formatting.
  12. Handle missing routes without throwing.
  13. 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.

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).

Sources

  • SAIF.Framework.Core\V1\Api\clsBusinessApiCriteriaBase.vb