Free lesson · AWS Fundamentals

Reading AWS documentation and the service API model

Easy6 min read

Everything Is An API

There is one structural fact that makes AWS learnable: every AWS service is an API, and every interface you use is a client of that API.

graph TD
    C[Console] --> API[Service API endpoint<br/>SigV4-signed HTTPS]
    CLI[AWS CLI] --> API
    SDK[SDK - Python, Java, Go, JS] --> API
    CFN[CloudFormation / CDK] --> API
    TF[Terraform] --> API
    API --> CP[Control Plane<br/>create, configure, describe]
    API --> DP[Data Plane<br/>read/write your actual data]

This diagram shows that every AWS interface is a client of the same service API. The Console, the AWS CLI, the language SDKs, CloudFormation and CDK, and Terraform all issue signed HTTPS requests to a service API endpoint. That API is divided into a control plane, which creates, configures, and describes resources, and a data plane, which reads and writes your actual data.

Three consequences follow, and they are worth internalising:

Anything the console does, you can automate. If the console can do it, there is an API action for it. If you cannot find the action, open the browser's network tab while performing the operation.

Anything the console does, IAM can allow or deny. Permissions are expressed in terms of API actions, not console screens. "Give them read-only access to the billing page" becomes a set of specific actions.

The control plane and the data plane fail independently. This distinction matters enormously during incidents. Your EC2 instances keep running (data plane) when the EC2 API is degraded and you cannot launch new ones (control plane). S3 keeps serving objects when you cannot create buckets. Design runbooks that do not require control-plane operations during an outage - pre-provision the failover capacity rather than planning to create it under duress.

Where The Truth Actually Lives

AWS documentation is enormous and the same fact appears in several places with different levels of authority. Knowing which document is canonical for which kind of question saves hours.

Question	Canonical source
What does this service do, conceptually?	User Guide / Developer Guide
What exactly does this API action accept and return?	API Reference
What are the current limits?	Service Quotas page for that service, and the Service Quotas console
What availability does AWS commit to?	Service Level Agreement page - legally binding, distinct from marketing claims
What IAM actions, resources, and condition keys exist?	Service Authorization Reference
What does this cost?	Pricing page, plus the Pricing Calculator
What changed recently?	What's New feed and the service's Document History
How should I architect this?	Well-Architected, AWS Prescriptive Guidance, reference architectures

Tip: The Service Authorization Reference is the most underused document AWS publishes. It lists, for every service, every IAM action, which resource types each action supports, and which condition keys apply. When you need to write a least-privilege policy, this is the only complete source - the User Guide's example policies are illustrative, not exhaustive. Saying "I'd check the Service Authorization Reference for the condition keys" in an interview is a strong signal.

Important: An SLA is not a durability claim and neither is a marketing number. S3's famous durability figure is a design target describing expected annual object loss; the SLA is a separate document specifying availability commitments and the service credits you receive when they are missed. Neither promises your data survives you deleting it. When a design depends on a guarantee, read the SLA page, not the product page.

Reading An API Action

Every API Reference entry has the same shape, and learning to read it quickly is a durable skill.

Request parameters - which are required, which are optional, valid ranges, and constraints. Ranges are where hard limits are documented.
Response elements - what you get back, including whether the operation is asynchronous and returns an identifier rather than a result.
Errors - the exception types the action can raise. ThrottlingException tells you it is rate-limited. ResourceNotFoundException after a create tells you the API is eventually consistent.
Pagination - actions returning lists are almost always paginated. Ignoring the next-token means silently processing only the first page. SDK paginators handle this; hand-rolled loops usually do not.
Idempotency - many create actions accept a client token so that a retried request does not create a duplicate. Retry logic without an idempotency token is how one payment becomes three.

Warning: Control-plane APIs are often eventually consistent. Create an IAM role and immediately assume it, and the assume can fail. Create a subnet and immediately reference it, and the reference can fail. This is documented per-action but easy to miss, and it produces flaky automation that works in testing and fails in CI. The fix is retry with backoff on the specific "not found" error, not a fixed sleep.

Verifying A Claim Quickly

A repeatable procedure for "is this true?", in the order that answers fastest:

Is it a limit? → Service Quotas console for the live value; quotas doc page for defaults and adjustability.
Is it a permission? → Service Authorization Reference for the action and condition keys; IAM Policy Simulator or Access Analyzer to test.
Is it a behaviour? → API Reference for the exact action, then the User Guide section.
Is it a guarantee? → SLA page. Not the product marketing page.
Is it a price? → Pricing page for the specific Region, then the Pricing Calculator.
Did it change? → What's New feed, then the document history at the bottom of the guide.

Tip: AWS documentation is versionless and undated on most pages - it describes the present, and the present changes. Blog posts, Stack Overflow answers, and training content age badly and give no signal that they have. Anything about limits, service availability, or pricing that you read outside the official docs should be treated as a hypothesis to verify, including the numbers in this course.

Common Failure Modes

Warning: Trusting a blog post over the docs. The most common source of confidently wrong AWS statements. Service behaviour changes; the post does not.

Reading the User Guide when you needed the API Reference. The User Guide describes the common path. Edge cases, exact constraints, and error conditions live in the API Reference.

Ignoring pagination. A list call that returns 50 of 4,000 items and reports success is a silent data bug.

Assuming console equals API. The console frequently performs several API calls behind one button and applies defaults you did not choose. IaC reproducing "what the console did" requires knowing which calls those were - CloudTrail shows you.

Confusing durability with availability with backup. Three different guarantees, three different documents, three different failure modes.

Copying an example IAM policy from a guide into production. Example policies are written for clarity, are frequently broader than needed, and often use wildcards the Service Authorization Reference would let you replace with specific actions.

Why This Matters In An Interview

Interview: What interviewers are listening for:

You separate control plane from data plane when discussing failure. This is a senior distinction and it comes up naturally in reliability questions.

You know where authoritative answers live rather than claiming certainty about numbers. "I'd verify the current quota, but the shape of the constraint is per-partition throughput" is a better answer than a confidently wrong figure.

You mention idempotency tokens and pagination when discussing API interaction. Both are small details that reliably distinguish people who have written production AWS integrations.

Common follow-ups:

"Region-wide event: what still works?" → Data plane for already-provisioned resources, mostly. Control plane, probably not. Then discuss what that means for a failover runbook that assumes you can launch instances.

"How do you write a least-privilege policy for a service you have never used?" → Service Authorization Reference for the action list, run in a non-prod account with broad permissions, read CloudTrail to see what was actually called, then narrow. IAM Access Analyzer can generate a policy from CloudTrail activity.

"Your automation works locally and fails in CI. Where do you look?" → Eventual consistency on control-plane creates, credential differences, Region defaults, and pagination. Naming eventual consistency first is the strong answer.

Practice

Exercise: Starter. Pick any service you use. Find its API Reference, its Service Quotas page, its SLA page, and its entry in the Service Authorization Reference. Note how differently each answers the question "what are the limits?"

Intermediate. Perform an operation in the console, then find it in CloudTrail and identify every API call the console made. Write the equivalent CLI commands.

Advanced. Take a permission a teammate requested as service:* and reduce it to the minimum action set using the Service Authorization Reference and CloudTrail. Document which conditions you added and what each one prevents.