The Amazon API Estate: 199 Surfaces, One Source of Truth, and What It Still Leaves Out

Last week I wrote about the Microsoft API estate. This week I re-profiled every live member of the Amazon API estate on APIs.io. That is 199 provider profiles, run in eleven waves, plus one I had to run by itself, and every one of them is better described than it was on Monday.

I did one thing differently this time. For Amazon, I made AWS’s own Smithy models the source of truth for every API contract in the estate. That decision shaped almost everything I found, so it is where I want to start.

What an estate is

An estate on APIs.io is every provider profile that declares a company as its parent. For Amazon, that tree is almost entirely Amazon Web Services: 196 of the 199 members sit under AWS. The other three are the Amazon parent itself, the Amazon Selling Partner API, and AWS. You can see the whole tree on the estate page, and every profile below links to its own page.

The scores in this post are from this week’s re-profile. The estate page updates with the weekend APIs.io build, so until then it will still show the older figures.

AWS already publishes its own contract

AWS does something most companies at its scale do not. It publishes a machine-readable model of every service it runs, in Smithy, in one public repository: aws/api-models-aws. That repository holds 436 service models. It is what AWS generates its own SDKs from.

So instead of trusting whatever OpenAPI we had gathered over the years, I generated every contract in the estate from those models:

• 186 members are now built from 343 Smithy models. Each model is pinned to the commit it was read at, with a record that the file we hold is byte-identical to what AWS published.
• A product is often several models. Amazon Bedrock is eight models, from the control plane to the runtime to AgentCore. Billing and Cost Management is fifteen. IAM now includes STS, which is how most callers actually get their credentials.
• The wire format is right. EC2 and IAM are form-encoded with XML responses, S3 is REST XML, DynamoDB is AWS JSON, and every contract declares SigV4 signing for what it is, rather than pretending it is a bearer token. Amazon SQS is a nice example: AWS moved it to the JSON protocol in 2023, and the model says so, while the spec we held before still described the old one.
• Every operation ID in every contract now matches the model exactly. I checked them all against the models.

Amazon Chime SDK went from no contract at all to 258 operations, because the model was sitting in AWS’s repository the whole time. That is what a vendor-published model buys you.

The investment shows

Across all 199 members, the mean Kin Score moved from 56.8 to 69.9, and the median is 71.3. 154 are exemplar and 40 strong. Only five members sit below strong.

The top of the estate:

• Amazon SES (84.4), AWS Clean Rooms (83.5), Amazon DynamoDB (82.9), CodeGuru Profiler (81.2), Amazon Lex (81.1), CloudFront (80.7), CloudSearch (80.6) and CodeDeploy (80.1).
• The core building blocks are all solidly exemplar: S3 77.2, Lambda 75.9, SageMaker 75.1, Amazon Q 73.2, IAM 68.7 and EC2 68.3.

The biggest movers were services that were simply under-described: Aurora DSQL +40.7, Audit Manager +39.7, Application Migration Service +37.4, Aurora +37.3, AppSync +36.9, AWS Backup +35.8 and Athena +31.5.

Agent readiness is ahead, but still the gap

Mean agent readiness across the estate is 38.8, up from 30.7. 98 members are at 40 or above. That is well ahead of where Microsoft sits, and most of it comes straight from the models: complete schemas, every modelled error, and honest authentication are exactly what an agent needs to call an API safely.

The leaders are Amazon Selling Partner API (67.9), AWS Glue (52.0), AWS Batch (51.5), Security Hub (50.8), Systems Manager (50.7) and the Amazon parent (50.6).

Still, a 31-point gap between Kin Score and agent readiness is the story here too. A model tells an agent how to call an operation. It does not tell it which of 17,000 operations to call, what a sensible workflow looks like, or what the operation costs. Those are the next layer.

Where the estate is not yet coherent

AWS retires services and leaves them in the catalog. I retired nineteen members in this pass, every one of them from AWS’s own Services in Full Shutdown list or its own end-of-support notice: FinSpace, IoT Events, Lookout for Metrics, Lookout for Vision, Lookout for Equipment, Panorama, RoboMaker, QLDB, Elastic Transcoder, SimSpace Weaver, Mechanical Turk, CodeStar, CodeGuru Security, MediaStore, App Mesh, Proton, Pinpoint, Snowball Edge and DeepRacer. Where AWS names a successor, I pointed the old pages at it: Elastic Transcoder at MediaConvert, MediaStore at S3, App Mesh at ECS. The good news is that AWS publishes that list at all. The harder news is that nineteen of the 218 profiles we held were for services that no longer exist.

A model per service does not map cleanly to a product. VPC, VPN, Transit Gateway, PrivateLink and Verified Access are all part of the EC2 model. Aurora is part of RDS, and Fargate is part of ECS. These are products people buy and search for by name, but there is no model to point at for them. They keep their hand-written contracts for now.

The same service ends up under two names. The estate carried both amazon-xray and aws-x-ray, built from the same X-Ray model. I merged them into Amazon X-Ray. Slugs still split between amazon-* and aws-*, which follows AWS’s own inconsistent branding.

Some products have no API at all. AWS App Studio is console-only. The contract we held for it pointed at a host that does not exist, so I removed it, and its score dropped to an honest 37.2. AWS CloudShell and the AWS CLI sit at the bottom for a similar reason: they are tools, not hosted APIs.

The estate is AWS, not Amazon. 93 of AWS’s 436 Smithy models have no member in the estate yet, including AWS Marketplace (eight models), Partner Central (five), Managed Workflows for Apache Airflow, AppStream, Resource Access Manager, Service Quotas and Elastic Disaster Recovery. And outside AWS, Amazon’s retail, advertising, Alexa and Prime surfaces are barely represented. The Selling Partner API is the only one, and it leads the estate on agent readiness.

One lesson from the run

I want to be honest about one thing that went wrong. After generating the contracts from Smithy, the older specs we held were still sitting beside them. Our own refine step quietly merged their operations back in, so about seventy members briefly carried every operation twice under two different names. Every score went up, so no score flagged it. I caught it by checking each contract’s operation IDs against the model, regenerated everything from Smithy, and moved the old specs aside for good.

The lesson is the same one AWS has already learned: one source of truth only works if nothing else is allowed to write to the same place.

Where I would invest next

1. Publish lifecycle in the model. AWS has a shutdown list, but the models do not say a service is closing. A deprecation date and a successor in the model would reach every SDK and every agent at once.
2. Model products, not just services. VPC, Aurora and Fargate need a way to be found as themselves, even if their operations live in EC2, RDS and ECS.
3. Add workflows and cost on top of the models. The contracts are complete. What agents need next is which operations go together, and what they cost to run.
4. Bring the rest of Amazon into the same practice. Retail, advertising and devices would benefit from the discipline AWS already applies to itself.

Amazon has already built the hardest part: a single, public, machine-readable source of truth for an enormous API surface. Most of what is left is metadata on top of it.

Every member of the estate

Here is every live profile in the Amazon estate, with this week’s Kin Score and agent readiness. Each name links to its page on APIs.io.

Amazon (3)

Amazon Web Services (196)

If you work on any of these services and something here is wrong, the estate page and each provider page let you correct it. I would rather be told than be wrong.