| name | api-efficiency-audit |
| description | Audit API design for chattiness and over-fetching — REST endpoints requiring N calls per screen, GraphQL resolvers with N+1 fan-out, default-everything payloads, missing pagination and field selection, provider-side polling where webhooks serve, and uncompressed responses. Use this skill whenever the user shares API schemas (OpenAPI, GraphQL SDL), resolver code, endpoint designs, or asks why clients make too many calls or payloads are heavy. Part of Lean Agentic AI Skills; emits lean-findings.json. |
API Efficiency Audit
Producer skill. Input: API specs, resolver/handler code, access logs or client call traces if available. Output: lean-findings.json.
An API's design fixes the energy budget of every client that ever calls it — a chatty design taxes servers, networks, and (mobile) client radios simultaneously. This skill audits the provider side; lean-mobile-audit covers the consumer side.
Subject type: emit subject.type: "api" in findings.
Signatures
- Chattiness by design — a screen/use-case requiring N sequential calls (resource → sub-resource → sub-sub); no aggregate/batch endpoint for the dominant client pattern. High. Evidence: the call sequence per use case from specs/traces. Fix: purpose-built aggregate endpoints, batch APIs, or query-shaped access (GraphQL/sparse fieldsets) — with the coupling trade-off named.
- GraphQL N+1 resolvers — per-node data fetches without DataLoader/batching; nested lists multiplying queries. High. Evidence: resolver code paths. (DB-side symptoms belong to db-efficiency-audit; the resolver design belongs here.)
- Over-fetching defaults — endpoints returning full objects where clients use a handful of fields; no fields/select parameter; GraphQL schemas encouraging
...everything fragments. High at volume. Evidence: payload samples vs client usage when provided.
- Missing or unbounded pagination — list endpoints returning everything; offset pagination on huge tables where cursors serve. High.
- Provider-side polling — clients forced to poll for state changes because no webhooks/SSE/push exists. Medium-high (multiplies across every client × interval). Fix: webhooks with retries or event streams; infrastructure cost named.
- No conditional requests — missing ETag/If-Modified-Since support on cacheable resources; clients re-download unchanged data. Medium. Pairs with caching-strategy-designer for the full design.
- Uncompressed/verbose payloads — no gzip/brotli on JSON; verbose envelope conventions (deeply nested wrappers, repeated metadata per item). Medium.
- Chunky where chatty is right — the inverse failure: giant payloads bundling rarely-used data into hot endpoints. Medium; balance is the point, and the evidence is client usage patterns.
- Retry guidance absent — no Retry-After/backoff contract, inviting client retry storms. Low-medium.
Honesty rules
Call counts and payload byte sizes from specs, samples, and logs are real — report them per use case. Aggregate endpoints trade flexibility and cache granularity — name it. Never redesign an API's shape from the spec alone when client usage data would change the answer; ask for traces or mark the pattern-level finding accordingly.
Cost signal (countable)
Cost drivers: API request count per user session and payload bytes per request. Both countable from specs and traces; each chattiness or over-fetching finding should quote them in cost_signal.
Not this skill's job
Database access under the handlers (db-efficiency-audit), client-side call behavior (lean-mobile-audit), HTTP cache layers (caching-strategy-designer).
