Reading AWS API Reference Docs Like an SDK Developer

The AWS API reference is written for the REST API, not your language.

Once you can translate a reference page into an SDK call, you can use any of the 200-plus AWS services from any SDK, even ones you have never touched.

Summary

Every AWS service has an API reference documenting its operations, request parameters, response shapes, and errors.

That reference is the source of truth. The boto3 and SDK v3 documentation are generated views of the same underlying model (Smithy), so they agree with it.

The mental translation is small. An operation name becomes a method or a command, and the parameter names stay almost identical.

The main thing to learn is casing. Operation names differ by language convention, but request and response field names do not.

Learn to read three parts of any reference page: the request parameters (what you send), the response elements (what you get), and the errors (what can go wrong).

Recipe

Read the operation name and required parameters from the reference, then write the equivalent call.

# --- Python (boto3) ---
# API reference operation: "GetObject" -> boto3 method get_object
import boto3
 
s3 = boto3.client("s3")
resp = s3.get_object(Bucket="my-bucket", Key="report.pdf")  # required params
print(resp["ContentType"])                                  # response element

// --- TypeScript (AWS SDK v3) ---
// API reference operation: "GetObject" -> GetObjectCommand
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const resp = await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "report.pdf" }));
console.log(resp.ContentType);   // response element, same name as the reference

When to reach for this:

• You are using a service or operation for the first time.
• The SDK's own docs are thin but the API reference is complete.
• You need to know exactly which parameters are required.
• You are debugging why a field is missing from a response.

Working Example

Here is the full translation for a DynamoDB Query, showing how required keys, optional keys, and paginated responses map across.

# --- Python (boto3) ---
# Reference: DynamoDB "Query"
#   Required: TableName, KeyConditionExpression
#   Optional: ExpressionAttributeValues, Limit
#   Response: Items (list), LastEvaluatedKey (paginated marker)
import boto3
 
ddb = boto3.client("dynamodb", region_name="us-east-1")
resp = ddb.query(
    TableName="Orders",
    KeyConditionExpression="customerId = :c",
    ExpressionAttributeValues={":c": {"S": "cust-42"}},
    Limit=25,
)
for item in resp.get("Items", []):
    print(item)
print("more pages?" , "LastEvaluatedKey" in resp)

// --- TypeScript (AWS SDK v3) ---
// Same "Query" operation and identical field names, PascalCase preserved.
import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";
 
const ddb = new DynamoDBClient({ region: "us-east-1" });
const resp = await ddb.send(new QueryCommand({
  TableName: "Orders",
  KeyConditionExpression: "customerId = :c",
  ExpressionAttributeValues: { ":c": { S: "cust-42" } },
  Limit: 25,
}));
for (const item of resp.Items ?? []) console.log(item);
console.log("more pages?", resp.LastEvaluatedKey !== undefined);

What this demonstrates:

• The operation name Query maps to query in boto3 and QueryCommand in SDK v3.
• Every request field (TableName, KeyConditionExpression) keeps its PascalCase from the reference.
• Response elements (Items, LastEvaluatedKey) also match the reference names exactly.
• A LastEvaluatedKey in the response is the reference's signal that the operation paginates.

Deep Dive

How It Works

• AWS defines each service with a Smithy model listing operations, input/output shapes, and errors.
• The API reference, boto3 docs, and SDK v3 types are all generated from that one model, so they stay in sync.
• The only per-language transformation is the naming convention for the operation itself.
• Field names inside requests and responses are passed through unchanged.

Casing Cheat Sheet

Reading the Three Sections

• Request parameters: each is marked required or not, with its type and constraints. Send at least the required ones.
• Response elements: the shape you get back; optional elements may be absent, so guard them.
• Errors: the exceptions the operation can throw, which map to ClientError codes (boto3) or typed exception classes (SDK v3).

Finding the Right Page

• Each service has its own reference, for example "Amazon S3 API Reference" or "Amazon DynamoDB API Reference."
• The boto3 reference lists every method with its exact parameter names and is often faster to skim.
• The SDK v3 API docs publish per-command input and output TypeScript types you can rely on for autocomplete.

Gotchas

• Guessing the casing - operation casing differs by language but field casing does not. Fix: check the reference; keep request and response fields PascalCase in both languages.
• Assuming a field is always present - many response elements are optional. Fix: use .get() in Python and ?? [] or optional chaining in TypeScript.
• Missing a required parameter - the reference marks these clearly. Fix: read the "Required" flag before writing the call.
• Ignoring the errors section - operations throw specific errors worth handling. Fix: map documented errors to ClientError codes or typed SDK v3 exceptions.
• Overlooking pagination - a NextToken, Marker, or LastEvaluatedKey in the response means there is more data. Fix: use a paginator instead of reading one page.
• Confusing the low-level and resource APIs (boto3) - boto3.client mirrors the reference; boto3.resource is a higher-level abstraction with different names. Fix: match the reference with the client API.

Alternatives

FAQs

Related

• What an AWS SDK Actually Does - the model the reference describes.
• AWS SDK Fundamentals Basics - applying reference reads to real calls.
• Anatomy of an AWS API Request - what the SDK does with the parameters you send.
• Service Endpoints, Partitions & Dual-Stack/FIPS Variants - per-service region and endpoint support.

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