{
  "id": "p_qNFFUA8yoZ75TzIc",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_qNFFUA8yoZ75TzIc",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You are a developer at a small advocacy group, and the supporter CRM you rely on is NationBuilder. Your task this week is to build an integration that pulls supporters, filters them by membership, and lets an automated agent add new signups with their tags. You want to know two things before you ship: how do you ask the API for exactly what you need, and what happens when something goes wrong halfway?\n\nYou start with NationBuilder's own article, Using parameters to interact with the NationBuilder API. APIs.io, which tracks the provider, notes that NationBuilder has written the parameter reference that most JSON:API providers leave to the specification. The article walks six conventions in order: filtering, pagination, sparse fields, sorting, sideloading and sideposting.\n\nThe filter grammar is the part you will use most. A bare filter matches, and bracketed operators narrow it. There is eql for case sensitivity, prefix, suffix and match for substrings, gt, gte, lt and lte for numbers, and a not_eq against null for existence checks. Index endpoints return 20 results by default. Page size and page number are bracketed parameters, and every response carries self, prev and next links. Sparse fieldsets, a minus sign for descending sort, and include for related resources round out the read side.\n\nThen you reach the sentence that could save you a bug. Filtering on a sideloaded resource, such as active memberships, \"does not remove unassociated Signups from the response. Signups without an active membership will still be included in the payload.\" If you read that parameter as a WHERE clause, you will ship the wrong list. The filter shapes what is included, not who is returned.\n\nOn the write side, you find sideposting. One request creates a signup, a recruiter and two new tags, binding them with temp-id values and a method of create or update on each relationship. It is tidy, and it fits your agent's job well.\n\nNone of this reads like marketing. APIs.io says nothing in the article is a marketing figure: it is a vendor describing its own query surface, and the description matches the JSON:API conventions the catalog already records. The catalog holds NationBuilder across 41 API pages, and the article walks four of them. Every example is a query against the Signups API, the nested filter reaches into the Memberships API, the sideposting payload creates records in the Signup Tags API, and the include example pulls from the Signup Taggings API.\n\nSo far the vendor looks careful. Then you look at what the catalog says about the record behind the article.\n\nThe agentic access profile maps 190 operations, 108 of them acting. For a supporter CRM that holds donations and voter data, that is a large write surface. The Kin Score is 65.0, in the strong band, with access clarity at 84.2 and discoverability at 73.2. Contract governance sits at 31.8. The Agent Readiness score is 37.1, agent-ready, with spec presence, OpenAPI examples, error semantics, the rate limit signal and agent skills all lit.\n\nIdempotency is unlit.\n\nRead that next to the sideposting example and picture your agent at work. It sends one POST that creates a signup, a recruiter and tags in a single transaction, identified by client-chosen temp-ids. The request times out. The agent does what agents do and retries. According to the catalog's reading, that retry creates all of them twice. The article documents how to compose that request precisely. Nothing in the record documents how to make it safe to repeat.\n\nThis is the turn in the story: the provider's own documentation is strong where it describes queries, and the catalog's record of the same provider shows a gap exactly where your integration will be most exposed.\n\nWhat you take away is practical. Use the filter grammar and the pagination links as documented, and remember that a filter on a sideloaded resource will not drop the parent records. Treat every one of the 108 acting operations as unsafe to retry blindly until you have built your own guard, such as checking for an existing record before you create one. And when you read any vendor's parameter reference, ask the second question too: not only how to compose the request, but how to repeat it safely.\n\nRead the original: https://apis.io/2026/11/06/nationbuilder-documents-six-json-api-parameters-and-108-acting-operations-have-no-idempotency/",
  "title": "You Can Compose the Request Exactly, but Nothing Says It's Safe to Repeat",
  "topics": [
    "nationbuilder",
    "json-api",
    "idempotency",
    "agent-readiness"
  ],
  "published_at": "2026-11-06T15:20:15.357Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}