---
title: HttpRequestExtensions
summary: API reference for HttpRequestExtensions.
status: draft
owner: andmil
last_reviewed: 2026-09-15
library: SAIF.Web.API
reference_type: package
---

# HttpRequestExtensions

`HttpRequestExtensions` is a static class of extension methods on `System.Net.Http.HttpRequestMessage`. It exists to give the rest of the library (and consumers) a single, non-throwing way to read the first value of a named request header, so header-driven logic never needs its own null-checking boilerplate around `HttpHeaders.TryGetValues`. It is used internally by `ApiResponseHandler.BuildTraceMessage` to read the client-identity headers (`Client-Name`, `Client-Is-Web`, `Client-User`, `Application-ID`) embedded in trace output.

## Purpose
- Provides a header lookup that never throws regardless of whether the `Headers` collection is null, the key is absent, or the header exists with an empty value collection — see [BR-WEBAPI-019](../../business-rules.md#br-webapi-019-header-reads-never-throw).

## Context
- Namespace: `SAIF.Web.API`
- Assembly/package: `SAIF.Web.API` (NuGet)
- Static class, extension methods (no base type)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `TryGetFirstHeader` | `public static string TryGetFirstHeader(this HttpRequestMessage request, string key)` | Returns the first value of the named header if `request.Headers` is non-null and `TryGetValues(key, out values)` succeeds; returns `""` when the header collection is null or the key is absent; may return `null` if the header exists but its value collection is empty — see [BR-WEBAPI-019](../../business-rules.md#br-webapi-019-header-reads-never-throw). |

## Behavioral notes
- The `null`-returning edge case (header present but with an empty value collection) is a documented gap between the method's "never throws" guarantee and its "always returns a usable string" implication — callers that assume a non-null return should account for it.*

## Constraints and usage notes
- Because this is an extension method, it is available on any `HttpRequestMessage` instance once the `SAIF.Web.API` namespace is imported; it requires no dependency-injection setup.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts.

## Sources
- `src/SAIF.Web.API/HttpRequestExtensions.cs`
- `src/SAIF.Web.API/ApiResponseHandler.cs`