Core SDK Mechanics Basics

Six short examples that show what a client actually does when you build it and call it.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3), so you can see the mechanics translate one to one.

Prerequisites

• Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-s3 (Node.js 18+).
• Credentials configured once via aws configure, environment variables, or an IAM role.
• Nothing here mutates data; every call is a read or a local inspection.

Basic Examples

1. Construct a Client With an Explicit Region

The region you pass is what drives endpoint resolution, so always set it.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3", region_name="us-east-1")
print(s3.meta.region_name)   # us-east-1

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
console.log(await s3.config.region());   // us-east-1

• Passing region_name / region makes behavior reproducible across machines.
• Construction does no network call, so this line is fast and offline.
• Omitting the region falls back to the environment, then shared config.
• If nothing supplies a region, the SDK raises when you make the first call.

Related: Regions, Endpoints & Client Construction - why region is mandatory.

2. Inspect the Resolved Endpoint

You can read the hostname the SDK computed before sending anything.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3", region_name="eu-west-1")
print(s3.meta.endpoint_url)   # https://s3.eu-west-1.amazonaws.com

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "eu-west-1" });
const endpoint = await s3.config.endpoint?.();
console.log(endpoint?.hostname);   // s3.eu-west-1.amazonaws.com

• boto3 exposes the resolved URL on client.meta.endpoint_url.
• SDK v3 gives you an async config.endpoint() returning a parsed URL object.
• Change the region and the hostname changes with it, confirming resolution works.
• This is the fastest way to debug a request that seems to go to the wrong place.

3. Attach a Config Object

Retries, timeouts, and endpoint variants are set through config.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(retries={"max_attempts": 5, "mode": "standard"})
s3 = boto3.client("s3", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({
  region: "us-east-1",
  maxAttempts: 5,          // total attempts, including the first
  retryMode: "standard",
});

• boto3 collects tuning into a botocore.config.Config object passed as config.
• SDK v3 takes the same knobs as top-level constructor fields.
• max_attempts counts total tries; the default retry mode already handles throttling.
• Set config once at construction; it applies to every call the client makes.

Related: Timeouts & Connection Configuration - the timeout knobs in depth.

4. Make a Call and Read Response Metadata

Every response includes metadata alongside the business data.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3", region_name="us-east-1")
resp = s3.list_buckets()
print(resp["ResponseMetadata"]["RequestId"])
print(resp["ResponseMetadata"]["HTTPStatusCode"])   # 200

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
const resp = await s3.send(new ListBucketsCommand({}));
console.log(resp.$metadata.requestId);
console.log(resp.$metadata.httpStatusCode);   // 200

• boto3 puts metadata under the ResponseMetadata key of the response dict.
• SDK v3 attaches it to a $metadata property on the response object.
• The request id uniquely identifies the call for AWS support and log correlation.
• Log the request id on every failure, not just successes.

5. Catch a Typed Error and Read Its Code

Failed calls surface as typed errors that carry a service error code.

# --- Python (boto3) ---
import boto3
from botocore.exceptions import ClientError
 
s3 = boto3.client("s3", region_name="us-east-1")
try:
    s3.head_bucket(Bucket="a-bucket-that-does-not-exist-xyz")
except ClientError as err:
    print(err.response["Error"]["Code"])                  # 404
    print(err.response["ResponseMetadata"]["RequestId"])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, HeadBucketCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
try {
  await s3.send(new HeadBucketCommand({ Bucket: "a-bucket-that-does-not-exist-xyz" }));
} catch (err) {
  const e = err as { name: string; $metadata?: { requestId?: string } };
  console.log(e.name);                    // NotFound
  console.log(e.$metadata?.requestId);
}

• boto3 raises ClientError; read the code from err.response["Error"]["Code"].
• SDK v3 throws an error whose name is the service error code.
• Both carry the request id, so log it even on the failure path.
• Branch on the code rather than the human-readable message, which can change.

6. Override the Endpoint for Local Testing

Point the client at a local emulator by supplying an explicit endpoint.

# --- Python (boto3) ---
import boto3
 
# Override bypasses resolution: the SDK sends exactly here.
s3 = boto3.client(
    "s3",
    region_name="us-east-1",
    endpoint_url="http://localhost:4566",   # LocalStack
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
// Override bypasses resolution: the SDK sends exactly here.
const s3 = new S3Client({
  region: "us-east-1",
  endpoint: "http://localhost:4566",   // LocalStack
});

• An override replaces resolution entirely, so no dual-stack or FIPS logic runs.
• This is ideal for LocalStack, MinIO, or another test double.
• Keep the override behind an environment check; never freeze it into production.
• A region is still required because signing needs one even with an override.

Related: Custom Endpoints & VPC Endpoints (PrivateLink) - overrides for private connectivity.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).