Low-Level Clients vs the Resources API

boto3 gives you two ways to talk to many services: the low-level client and the higher-level Resources API. This page explains why new code should default to clients, and where resources still earn their place.

The Resources API is a boto3-only concept, so the boto3 examples are plain Python. Where it helps, we contrast with the AWS SDK for JavaScript v3 in prose.

Recipe

Default to the low-level client. Its methods map one-to-one onto the AWS API, so everything in the API reference is available and nothing is hidden.

import boto3
 
# Low-level client: explicit, complete, and the actively developed surface.
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"])

When to reach for this:

• You are writing new code and want full, current API coverage.
• The service is recent and simply has no resource layer.
• You need explicit control over pagination, batching, and request shape.
• You want the surface that AWS actively maintains.

Working Example

The same "delete everything under a prefix" task, first with a resource (concise) and then with a client (explicit). Both are correct; the trade-off is readability versus visibility.

import boto3
 
# --- Resources API: reads like objects, but each step may hit the network ---
s3_resource = boto3.resource("s3")
bucket = s3_resource.Bucket("my-bucket")
bucket.objects.filter(Prefix="tmp/").delete()   # iterate + batch-delete, hidden
 
# --- Low-level client: every request is visible and under your control ---
s3 = boto3.client("s3")
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket="my-bucket", Prefix="tmp/"):
    keys = [{"Key": o["Key"]} for o in page.get("Contents", [])]
    if keys:
        s3.delete_objects(Bucket="my-bucket", Delete={"Objects": keys})

What this demonstrates:

• The resource version is shorter but hides how many list and delete calls it makes.
• The client version spells out pagination and batching, so cost and behavior are obvious.
• Resource collections like bucket.objects are lazy; iterating them triggers API calls.
• Both ultimately call the same S3 APIs; the resource just wraps them.

Deep Dive

What Each One Is

• A client is a thin, generated wrapper. Each method (get_object, put_item) maps to exactly one AWS operation, and the response is a plain dict.
• A resource is an object layer built on top of a client. It exposes entities (Bucket, Object, Table) with attributes and collections, and lazily calls the client underneath.

Why Clients Are the Default Now

• The Resources API is in maintenance mode: AWS adds no new features to it and no longer generates resources for new services.
• Coverage is partial. S3, DynamoDB, SQS, SNS, EC2, and a handful of others have resources; most newer services do not.
• Clients are complete and current, so defaulting to them means you are never blocked by a missing resource.

Where Resources Still Fit

• Quick scripts and notebooks where bucket.objects.all() is simply pleasant to read.
• Existing codebases already built around resources, where consistency matters more than migrating.
• Simple entity traversals where the hidden calls are few and the ergonomics win.

Dropping From a Resource to Its Client

• Every resource exposes its underlying client at .meta.client, so you are never stuck.

import boto3
 
s3_resource = boto3.resource("s3")
client = s3_resource.meta.client   # the low-level client behind the resource
client.put_object(Bucket="my-bucket", Key="k.txt", Body=b"hi")

The SDK v3 Contrast

The AWS SDK for JavaScript v3 never had a resource layer. It is client-only: you construct a service client and send command objects. There is no Bucket or Table object abstraction to choose. In other words, the "clients vs resources" decision does not exist in v3, because only clients exist.

// AWS SDK v3 is client-only: no resource abstraction to weigh.
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const out = await s3.send(new ListObjectsV2Command({ Bucket: "my-bucket", Prefix: "logs/" }));
for (const obj of out.Contents ?? []) console.log(obj.Key, obj.Size);

So when you port boto3 resource code to another language, expect to rewrite it in the client style, because that is all the other SDK offers.

Gotchas

• Hidden network calls behind attributes - reading bucket.creation_date or iterating bucket.objects triggers API calls you did not write. Fix: know which resource attributes are lazy, or use the client when cost visibility matters.
• Reaching for a resource that does not exist - boto3.resource("newservice") raises for services without a resource layer. Fix: default to boto3.client for anything but the classic handful.
• Assuming resources are thread-safe - they are not; sharing a resource across threads is unsafe. Fix: one resource per thread, or share a client instead.
• Expecting new features on resources - the Resources API is frozen, so recently added parameters may only appear on the client. Fix: use the client for anything cutting-edge.
• Mixing mental models - blending resource objects and raw client dicts in one function gets confusing. Fix: pick one style per module, and drop to .meta.client deliberately when needed.

Alternatives

FAQs

Related

• boto3's Session, Client & Resource Model - where clients and resources come from.
• boto3 Fundamentals Basics - the low-level client loop.
• Typed boto3 with boto3-stubs & mypy-boto3- - typing clients for autocomplete.
• boto3 Fundamentals Best Practices - client reuse and cost habits.

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