SDK and REST API Patterns

Quick Answer: Azure AI SDKs follow a consistent pattern: create client → call method → process response. REST APIs use Ocp-Apim-Subscription-Key header. Long-running operations use pollers. Handle 401 (auth), 429 (rate limit), and content_filter errors.

Universal SDK Pattern

Every Azure AI service SDK follows the same structure:

# 1. Import the client and credential classes
from azure.ai.<service> import <ServiceClient>
from azure.core.credentials import AzureKeyCredential
# OR for Entra ID:
from azure.identity import DefaultAzureCredential

# 2. Create the client
client = <ServiceClient>(
    endpoint="https://<resource>.cognitiveservices.azure.com/",
    credential=AzureKeyCredential("<key>")
    # OR credential=DefaultAzureCredential()
)

# 3. Call a method
result = client.<method>(input_data)

# 4. Process the response
for item in result:
    print(item.property)

REST API Pattern

POST https://<resource>.cognitiveservices.azure.com/<service-path>?api-version=<version>

Headers:
    Ocp-Apim-Subscription-Key: <your-key>
    Content-Type: application/json

Body:
{
    // Service-specific request body
}

Service-Specific Endpoint Patterns

On the Exam: Note that Translator uses a different base URL (api.cognitive.microsofttranslator.com) than other services. AI Search uses a different domain (search.windows.net). Azure OpenAI uses (openai.azure.com). Knowing the correct endpoint pattern is tested.

Long-Running Operations

Operations like model training and batch processing are asynchronous:

# SDK pattern — returns a poller
poller = client.begin_analyze_document(model_id="prebuilt-invoice", body=file)
result = poller.result()  # Blocks until complete

# REST pattern — returns an operation URL
# POST returns 202 Accepted with Operation-Location header
# Poll the operation URL until status is "succeeded"
operation_url = response.headers["Operation-Location"]

Error Handling

from azure.core.exceptions import (
    HttpResponseError,
    ClientAuthenticationError,
    ResourceNotFoundError
)

try:
    result = client.analyze_text(request)
except ClientAuthenticationError:
    print("401: Invalid key or unauthorized")
except ResourceNotFoundError:
    print("404: Resource or endpoint not found")
except HttpResponseError as e:
    if e.status_code == 429:
        print("429: Rate limit exceeded — retry after backoff")
    elif "content_filter" in str(e):
        print("Content blocked by safety filter")
    else:
        print(f"Error {e.status_code}: {e.message}")

Common HTTP Status Codes