AWS SDK Fundamentals Basics

Seven examples to get you started with the AWS SDK - five basic and two intermediate.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3).

Prerequisites

• Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-s3 (or the client for whichever service you need; Node.js 18+).
• Credentials configured once via aws configure, environment variables, or an IAM role. The SDK finds them automatically.
• A default region, set with AWS_REGION or AWS_DEFAULT_REGION, or passed per client.

Basic Examples

1. Create a Client

The starting point for every call is a service client bound to a region.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3", region_name="us-east-1")
print(type(s3))   # <class 'botocore.client.S3'>

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

• boto3 uses one factory (boto3.client) for every service, selected by string name.
• SDK v3 imports a dedicated S3Client class from its own package, which keeps bundles small.
• The region can also come from AWS_REGION, so you may omit it here.
• Creating a client is cheap and does no network call; reuse it across requests.

Related: What an AWS SDK Actually Does - the client-request-response model.

2. Make Your First Call

Call an operation on the client and get a structured response back.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
response = s3.list_buckets()
for bucket in response["Buckets"]:
    print(bucket["Name"])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const response = await s3.send(new ListBucketsCommand({}));
for (const bucket of response.Buckets ?? []) {
  console.log(bucket.Name);
}

• boto3 exposes operations as methods directly on the client (list_buckets).
• SDK v3 wraps each operation in a Command object you pass to client.send().
• Both calls hit the same S3 ListBuckets API and return the same data.
• SDK v3 responses use optional fields, so guard arrays with ?? [].

Related: Anatomy of an AWS API Request - what happens on the wire.

3. Read the Response

Responses are native objects: a dict in Python, a typed object in TypeScript.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
head = s3.head_object(Bucket="my-bucket", Key="report.pdf")
print(head["ContentLength"], head["ContentType"])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, HeadObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-bucket",
  Key: "report.pdf",
}));
console.log(head.ContentLength, head.ContentType);

• Response keys mirror the AWS API reference exactly, in PascalCase in both languages.
• HeadObject fetches metadata only, without downloading the object body.
• In Python, missing optional keys raise KeyError; use .get() when a field may be absent.
• In TypeScript, optional fields are typed as possibly undefined.

Related: Reading AWS API Reference Docs Like an SDK Developer - map docs to fields.

4. Pass Input Parameters

Most operations take an input object whose keys match the API.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
s3.put_object(
    Bucket="my-bucket",
    Key="notes/hello.txt",
    Body=b"hello world",
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "notes/hello.txt",
  Body: "hello world",
}));

• Input keys are identical across languages because they come from the same API contract.
• Body accepts bytes, strings, or streams; large uploads should stream rather than buffer.
• Required versus optional parameters are listed in each operation's API reference.
• A successful PutObject returns metadata like ETag you can store for validation.

5. Handle Errors

AWS calls fail as typed errors you catch and inspect.

# --- Python (boto3) ---
import boto3
from botocore.exceptions import ClientError
 
s3 = boto3.client("s3")
try:
    s3.get_object(Bucket="my-bucket", Key="missing.txt")
except ClientError as err:
    print(err.response["Error"]["Code"])   # NoSuchKey

// --- TypeScript (AWS SDK v3) ---
import { S3Client, GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
try {
  await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "missing.txt" }));
} catch (err) {
  if (err instanceof NoSuchKey) console.log("NoSuchKey");
}

• boto3 raises ClientError for API errors; read the code from err.response["Error"]["Code"].
• SDK v3 throws typed exception classes like NoSuchKey you can match with instanceof.
• Both expose the service error code and a request id useful for support cases.
• Never swallow errors silently; branch on the error code and log the rest.

Related: How AWS Bills SDK Calls - failed retries still cost requests.

Intermediate Examples

6. Paginate a Large Result Set

Many list operations return one page at a time; paginators walk them for you.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3")
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket="my-bucket", Prefix="logs/"):
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, paginateListObjectsV2 } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const pages = paginateListObjectsV2(
  { client: s3 },
  { Bucket: "my-bucket", Prefix: "logs/" },
);
for await (const page of pages) {
  for (const obj of page.Contents ?? []) console.log(obj.Key, obj.Size);
}

• Pagination hides the ContinuationToken bookkeeping the raw API requires.
• boto3 exposes get_paginator(operation_name); SDK v3 ships paginate<Operation> helpers.
• Each page is a separate HTTPS request, so a large prefix can mean many billed calls.
• Filter with Prefix to fetch only the keys you need.

Related: Reading AWS API Reference Docs Like an SDK Developer - spot paginated operations.

7. Call a Second Service

The same model applies to every service; only the client and operation change.

# --- Python (boto3) ---
import boto3
 
ddb = boto3.client("dynamodb", region_name="us-east-1")
ddb.put_item(
    TableName="Visits",
    Item={"id": {"S": "user-7"}, "count": {"N": "1"}},
)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
 
const ddb = new DynamoDBClient({ region: "us-east-1" });
await ddb.send(new PutItemCommand({
  TableName: "Visits",
  Item: { id: { S: "user-7" }, count: { N: "1" } },
}));

• Switching services means a new client (dynamodb) and new operations (PutItem), nothing more.
• DynamoDB uses typed attribute values ({"S": ...}, {"N": ...}) in the low-level client.
• Install only @aws-sdk/client-dynamodb in TypeScript; boto3 already includes every service.
• The client-request-response shape is identical no matter which service you target.

Related: AWS SDK vs Console vs CLI vs IaC - when the SDK is the right surface.

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