{
  "id": "p_xC5Tdr7H6x4j_czx",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_xC5Tdr7H6x4j_czx",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apievangelist"
  },
  "body": "A short piece of fiction, written by API Evangelist. The reader is imagined; the post, and every number and quotation from it, is real: \"The Amazon API Estate: 199 Surfaces, One Source of Truth, and What It Still Leaves Out,\" Kin Lane, November 12, 2026, https://apievangelist.com/2026/11/12/the-amazon-api-estate-199-surfaces-one-source-of-truth-and-what-it-still-leaves-out/\n\nMarisol runs platform tooling for a company that makes shipment-tracking software. She opened the post on a Thursday afternoon because the headline had a number in it, and she can't resist a number.\n\nShe read the first part the way she reads most things, looking for the place where it stops being true. It was a long way down. The author had made AWS's own Smithy models the source of truth for every contract in the estate: 186 members built from 343 models, each pinned to a commit. Marisol liked that more than she wanted to. Her own team had three different OpenAPI files for one internal service, and nobody could say which one was real.\n\nShe was less comfortable with the scores. The mean Kin Score had moved from 56.8 to 69.9, and the author had done the re-profiling and also designed the yardstick. A rising number measured by the person who raised it made her wary. She wrote that on a sticky note and then felt a bit unfair, because the post didn't hide the awkward parts. The author admitted that about seventy members had briefly carried every operation twice under two different names. Marisol stopped on this sentence: \"Every score went up, so no score flagged it.\" The mistake was invisible precisely because the metric rewarded it. She thought about the dashboards at her own job, which turned green whenever coverage rose, whether or not the coverage was real.\n\nThe next passage she reread twice. The old specs had sat beside the generated ones, and the refine step had quietly merged them back in. The author's conclusion was that \"one source of truth only works if nothing else is allowed to write to the same place.\" She didn't find that profound. She found it uncomfortably specific, because she knew exactly which folder in her repository had two files in it.\n\nShe disagreed with one thing, and she let herself keep disagreeing. The author wanted workflows and cost added on top of the models. Marisol thought a model with a lifecycle field would help agents more than a pile of recommended workflows, which would go stale the moment a service changed. The post did list lifecycle first among the investments, though. She grudgingly admitted she'd skimmed past it. Still, she doubted anyone would get the cost metadata right. The gap the author described, where a model says how to call an operation but not \"which of 17,000 operations to call\", sounded real to her, but filling it sounded like a decade of work.\n\nShe scrolled the long table without reading it, then went back and found the line near the bottom about corrections. The author wrote that they would rather be told than be wrong. She had nothing to correct. She just noticed the tone.\n\nThen she did something small. She opened her repository, found the service with three contracts, and wrote a short script. It listed every operation ID in the generated client and checked each one against the file everyone had agreed was canonical. Eleven were missing, and four appeared twice under slightly different names.\n\nShe didn't fix any of them. She put the list in a ticket, moved the two older specs into a folder called retired, and left the ticket assigned to herself for Monday.",
  "title": "Fiction: A reader of \"The Amazon API Estate: 199 Surfaces, One Source of Truth, and What It Still Leaves Out\"",
  "topics": [
    "apis",
    "api-evangelist",
    "fiction"
  ],
  "published_at": "2026-11-12T14:25:30.193Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}