Microsoft AI-103: REST API Contracts for Azure AI
A REST call to an AI endpoint looks like an ordinary HTTP request, but the response may represent generated text, a proposed tool action, a partial stream or an asynchronous job. Treating all of those as a successful string response creates reliability and security problems. Microsoft Foundry and connected Azure AI services expose different endpoints and API versions, so an application needs a clear contract for authentication, request shape, timeouts, output validation and error recovery. Good REST integration makes model variability explicit while keeping business operations deterministic. A 200 response from the model is only one step toward a verified user outcome.
On this page
- Identify the actual endpoint and version contract
- Authenticate with appropriate rights and transport security
- Validate requests before they reach a model
- Parse model outputs as untrusted content
- Handle errors with explicit retry classes
- Implement streaming and long-running operations honestly
- Build a change-safe API client boundary
Identify the actual endpoint and version contract
Determine whether the request targets a Foundry project, a model-inference endpoint, an Azure OpenAI-compatible path, Azure AI Search or a specialized service such as Document Intelligence. Their resource URLs, authentication audiences and supported API versions may differ. Do not reuse a code snippet from an unrelated endpoint merely because both are called “Azure AI.” Read the current Microsoft Learn contract for the selected resource and record the deployment name, supported model features and expected response format. A Microsoft AI-103 REST API client should verify response contracts, status codes, and retry safety rather than relying on a single successful request.
Centralize base URLs and API-version settings under controlled configuration. A published API version can support fields that a previous version rejects, while a preview may change semantics or availability. Pin the exact version in tests, document a migration plan and reject accidental client fallbacks that conceal unsupported functionality. Avoid constructing URLs by concatenating unvalidated user input, particularly when a tool-using agent can influence the requested resource path.
Authenticate with appropriate rights and transport security
Prefer Microsoft Entra tokens and managed identities where the service supports them, using the minimum role needed at the relevant resource or data-plane scope. Some Azure AI endpoints support API keys; protect them with managed secret storage and rotation, never embed them in prompt content or query strings. Enforce HTTPS, validate certificates, restrict egress to approved service hosts and recheck network reachability for private endpoints. A valid token does not authorize an arbitrary tenant’s data if application-level filtering is missing.
Handle 401 and 403 differently. An expired or missing token may call for a controlled credential refresh; an authorization denial should be investigated rather than retried forever. Log service correlation IDs and resource identifiers without recording bearer tokens or private document payloads. Confirm that the identity used by the background worker matches the task’s authorization model, especially when an agent acts on behalf of a user rather than solely under an application identity.
Validate requests before they reach a model
Define typed request objects for allowed models, input size, output schema, generation settings and tool capabilities. Put business constraints in conventional validation code rather than trusting a client-provided prompt to describe them. A tool proposal must not let the model choose an arbitrary URL, SQL statement or destination without an allowlist and separate authorization. Normalize and bound user input according to the product’s task; apply file and content scanning where uploaded documents are part of the workflow.
Include stable idempotency identifiers where the API or surrounding business operation supports them. A timeout after sending an HTTP request can leave the caller uncertain about its outcome. If the request only generated text, a repeat may be acceptable within a bounded budget; if it triggered a tool that changed state, the application must reconcile the authoritative system before retrying. Distinguish inference retries from transactions that require exactly-once business effects.
Parse model outputs as untrusted content
A successful HTTP response can contain an unsupported claim or malformed structured fields. Inspect status, content type, response schema and documented error objects, then validate extracted data against application rules. Do not accept generated JSON merely because it parses: check required fields, allowed values, source references and invariants. Keep tool proposals separate from tool execution results so the application can enforce permissions and present honest completion status.
For retrieval-augmented responses, verify citation identifiers against the authorized source index rather than trusting URLs written by the model. For extraction tasks, retain source page or span evidence when provided by the service. If the result conflicts with an authoritative business record, flag it for review. Model output is lower-trust than the application’s authenticated state, even when a well-formed REST object carries it.
Handle errors with explicit retry classes
Distinguish validation and authorization errors from transient network, capacity and service failures. Use bounded exponential backoff with jitter for retryable responses such as certain throttling or server failures, honoring Retry-After where documented. Set per-request timeouts, a total workflow deadline and a cost budget. A service can return rate-limit errors because a deployment’s token or request allowance is exhausted; opening more parallel connections will often worsen the situation.
Suppose a client posts an extraction job to an Azure AI endpoint and the connection times out after the server accepted the request. Sending an identical POST immediately may create a second expensive job if the endpoint does not implement idempotency. Prefer the service’s documented operation identifier or idempotency mechanism, persist the accepted job reference and query its status before deciding to resubmit. A 429 rate-limit response calls for respecting current retry guidance and lowering concurrency; a malformed 400 request should usually be fixed, not retried; an expired token or missing role needs a separate authentication diagnosis. Retrying all failures with one exponential backoff helper can hide permanent errors and compound cost under load.
Treat the response body as untrusted and potentially incomplete. A generated JSON object may be syntactically valid while containing unauthorized tool arguments, invented field values or paths outside an allowed storage prefix. Validate against a versioned schema and business rules, and keep the raw confidential payload out of common telemetry. For streaming responses, define a clear final-completion signal before downstream code treats output as settled. A robust REST integration should let an operator distinguish a failed request, an accepted but unfinished job and a completed, validated business outcome. Use separate metrics for each rather than reporting every successful HTTP exchange as successful AI work.
Preserve failed request metadata for diagnosis without storing full sensitive prompts indiscriminately. A permanent unsupported API-version error requires a deployment or client fix, not more retries. A streaming request that fails after partial output may require a new user-facing status and safe cancellation semantics. Design recovery so the client never silently presents a truncated model response as a completed business action.
Implement streaming and long-running operations honestly
Server-sent or equivalent streaming responses can contain a sequence of partial text, tool-related events and a terminal state. Validate event ordering and do not rely on one undocumented event name across SDK or API versions. Protect clients against connection interruption and duplicated output after reconnect. The server should know whether the underlying task is still running, completed or canceled; the browser closing a connection does not necessarily cancel a side-effecting operation.
For long document processing or evaluation jobs, use the service’s supported asynchronous job interface or an application-owned durable queue. Return a stable task ID and allow callers to obtain status and results. Avoid holding an ordinary request open until an expensive workflow finishes. A truthful 202 Accepted-like status is appropriate only when work has actually been durably accepted; inventing progress percentages from elapsed time erodes the reliability of the API contract.
Build a change-safe API client boundary
Expose a small application interface around the provider-specific REST calls, including authentication, validation, error mapping and telemetry. Unit-test against recorded schema fixtures and controlled failure responses, and integration-test the exact supported endpoint and version in a nonproduction project. Verify model quality separately using held-out cases. A successful request/response test does not establish that the model respected a user’s permission or cited current evidence.
Document the endpoint, API version, deployment, request and response schemas, supported retries, ownership and planned deprecation review. When Microsoft changes supported paths or services, migrate through a testable client version rather than editing every call site. Safe REST patterns turn model endpoints into dependable components of an AI product, with explicit limits on what the model may suggest and what the business system will actually do.