⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
api-design-review
Review the design of an API surface, meaning an HTTP API (OpenAPI spec or route code), an SDK's public classes and functions, or a CLI. Checks naming and consistency, resource modelling, error design (stable codes, RFC 9457 problem details, request ids), versioning and breaking changes, pagination, filtering, idempotency and retries, rate limits, timeouts, long-running operations, webhooks, auth, partial updates, ID, time and money formats, SDK ergonomics and CLI conventions. Uses scripts to lint OpenAPI files, classify changes between two spec versions as breaking or safe, and dump an SDK's public surface. Writes review.md with a scorecard, ranked findings with rewrites, a breaking-change risk list and what is good. Use when the user says "review my API", "API design", "is this a breaking change", "OpenAPI review", "check my spec", "SDK ergonomics", "review my SDK", "review my CLI", or asks whether an API change is safe to ship. For onboarding and time to first success, use dx-audit instead.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
simcraft
Skills that teach Claude how to do hard things well.
24 skills for Claude Code, built from real projects, with the parts tutorials skip.
Install · Video · Engineering · Learning · Design · Planning
Each skill is a folder with a SKILL.md: the method, the judgement calls, and real, tested scripts for one kind of work. Claude Code loads the right one when your request matches. You don't call them by name, you just ask.
What makes them different: every skill covers what breaks, how to check the result, and how to tell good from good enough.
Install
git clone https://github.com/dotslashsimran/simcraft ~/simcraft
mkdir -p ~/.claude/skills
for s in ~/simcraft/skills/*/*/; do ln -s "${s%/}" ~/.claude/skills/; done
cd ~/simcraft && npm i
Then open Claude Code and ask for something, like "make a perspective-illusion loop of a rainy night street".
- Claude Code finds skills one folder deep, so the loop links each one into
~/.claude/skills. The categories are only for browsing. To install a single skill, link just that folder. - A few skills have a one-time setup script in their folder (for example
setup.shfor Whisper in rough-cut). Each SKILL.md says so at the top. - Needs: Python 3.9+, Node 18+ (for skills that drive a browser or render video), and ffmpeg on your PATH or set as
FFMPEG=/path/to/ffmpeg. - API keys (only image-gen uses them) are read from your environment or
~/.config/simcraft/keys.env. They never go in the repo.
Skills
🎬 Video
| Skill | What it does |
|---|---|
| perspective-illusion | Illustrated 3D loops in the Japanese perspective-illusion style: flat scenes that open into depth. |
| code-loop | Any three.js scene or shader rendered as a seamless loop, checked for seams, freezes and blinks. |
| reverse-engineer-video | Hand it a viral clip, get a remake plan: every cut, camera move and beat. |
| scripted-screencast | Product demos written as a script and rendered frame-perfect. No retakes. |
| repo-timelapse | Your git history as a video of the project growing. |
| rough-cut | Raw talking footage to a tight first cut: pauses, ums and retakes removed. |
| clean-audio | Voice cleanup that measures first, then keeps every word clear. |
| vox-explainer | Vox-style explainer graphics timed word by word to a voiceover. |
🧑💻 Engineering
| Skill | What it does |
|---|---|
| codebase-map | Learn an unfamiliar repo fast by tracing one real request end to end. |
| bisect-anything | Find the exact commit behind any regression, then the exact lines. |
| flaky-test-killer | Fix why a test is flaky, never with retries, and prove the fix. |
| benchmark-honestly | Benchmarks that survive scrutiny, with confidence intervals. |
| api-design-review | Review an API, SDK or CLI, and catch breaking changes. |
| security-threat-model | Threat-model your own app from its real code, LLM apps included. |
| dx-audit | Try a developer tool like a brand-new user and time it to first success. |
🧠 Learning
| Skill | What it does |
|---|---|
| paper-to-runnable | A research paper turned into the smallest honest implementation of its idea. |
| system-design-from-scratch | Build a tiny real system, load-test it, break it, write up the trade-offs. |
| from-scratch | Learn anything by building the smallest version of it, one step at a time. |
| teach-back | You explain it, Claude finds the gaps, you get a one-page cheat sheet. |
🎨 Design
| Skill | What it does |
|---|---|
| image-gen | Images with your own Gemini or OpenAI key, consistent across a set. |
| brand-kit | Learn a brand from its live site into a kit the other skills apply. |
🧭 Planning
| Skill | What it does |
|---|---|
| skill-router | Picks the right skill for a task, or a chain of two or three. |
| next-step | A big messy goal turned into one clear next action at a time. |
| video-script | Short video scripts that sound like you, built from your own ramble. |
Chains that work well
skill-router builds these on its own when a task has stages.
| Start with | Then |
|---|---|
| A viral clip | reverse-engineer-video → code-loop or perspective-illusion |
| A research paper | paper-to-runnable → vox-explainer |
| A new SDK | dx-audit → scripted-screencast |
| "It got slower" | benchmark-honestly → bisect-anything |
| A new job | codebase-map → flaky-test-killer |
| Raw footage | rough-cut → clean-audio |
Credits
image-gen was inspired by adamd9/skill-image-gen, and vox-explainer by Charlie Hills' vox-animation skill (both MIT). Everything here is written from scratch.
License
MIT © Simran Sachdeva
// HOW IT'S BUILT
// FILES
11 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/coding/api-design-review/SKILL.md6.8 KBf3c182cf4240upstream ↗
--- name: api-design-review description: Review the design of an API surface, meaning an HTTP API (OpenAPI spec or route code), an SDK's public classes and functions, or a CLI. Checks naming and consistency, resource modelling, error design (stable codes, RFC 9457 problem details, request ids), versioning and breaking changes, pagination, filtering, idempotency and retries, rate limits, timeouts, long-running operations, webhooks, auth, partial updates, ID, time and money formats, SDK ergonomics and CLI conventions. Uses scripts to lint OpenAPI files, classify changes between two spec versions as breaking or safe, and dump an SDK's public surface. Writes review.md with a scorecard, ranked findings with rewrites, a breaking-change risk list and what is good. Use when the user says "review my API", "API design", "is this a breaking change", "OpenAPI review", "check my spec", "SDK ergonomics", "review my SDK", "review my CLI", or asks whether an API change is safe to ship. For onboarding and time to first success, use dx-audit instead. --- # API design review This skill reviews the shape of an API, which is the names, resources, errors, formats and rules that every user has to learn. Most API design mistakes are cheap to fix before launch and expensive after it, because fixing them breaks clients. The review therefore puts the findings that would be breaking to fix later at the top. The judgement lives in `reference.md`, which has the scoring rubric, the severity scale, the rules for each area with citations to public guidelines (Google AIP, Microsoft REST API Guidelines, Stripe's API conventions, Zalando RESTful API Guidelines, IETF RFCs), and before and after rewrites. Read the sections that match the API before writing findings. The scripts need only Python 3.9 or newer and the standard library. They read JSON, and they read YAML with PyYAML if it is installed or with a small built-in parser if it is not. Files that use YAML anchors or tags need PyYAML or a JSON copy. ## 1. Find out what to review Ask one question at a time, and only for what is missing: - **What is the surface?** It can be an OpenAPI file, route code, an SDK (a Python package name or a `.d.ts` file), or a CLI (`--help` output or the command source). - **Who uses it?** Public, partner, or internal with one client. This sets severity (reference.md section 2). - **Is it launched?** Before launch, recommend breaking fixes freely. After launch, every fix must come with a migration path. - **Is there an old version to compare against?** If yes, run the diff in step 3. ## 2. Run the tools Set `S=~/simcraft/skills/coding/api-design-review/scripts`. **OpenAPI lint:** ``` python3 $S/lint_openapi.py openapi.yaml # text python3 $S/lint_openapi.py openapi.yaml --format md python3 $S/lint_openapi.py openapi.yaml --fail-on high # exit 1 for CI ``` It checks path and field case consistency, plural collections, verbs in paths, error schemas (missing, inconsistent, no machine code, no request id), undocumented 4xx and 5xx, list endpoints with no pagination or a bare array response, mixed ID and time formats, money as floats, creating POSTs without an Idempotency-Key, PATCH bodies with required fields, 429 without Retry-After, duplicate or missing operationIds, and unsigned webhooks. **SDK surface:** ``` python3 $S/sdk_surface.py my_package [--path src] [--depth 2] python3 $S/sdk_surface.py dist/index.d.ts ``` It prints the public tree (modules, classes, signatures, properties, constants) and hints about boolean flag arguments, long positional parameter lists, mutable defaults, `any`, optional parameters before required ones, timeouts that default to waiting forever, error classes with no common base, and missing docs. Importing a Python package runs its import code, so only run it on code the user trusts. **For a CLI**, there is no script. Run `<tool> --help` and the help for each subcommand, try one command with `--json` and with output piped to a file, check the exit code after a failing command (`echo $?`), and compare against reference.md section 17. **For route code with no spec**, export a spec if the framework can (reference.md section 18). Otherwise build the endpoint list by reading the routes. The scripts find patterns, and they also produce false positives. Read every finding, drop the ones that are wrong for this API, and say which areas the scripts cannot check (behaviour, defaults, docs quality, real latency). ## 3. Check breaking changes When there are two versions: ``` python3 $S/breaking_diff.py old.json new.yaml [--format md] ``` It sorts every change into BREAKING, RISKY or SAFE, says why, shows where changed shared schemas are used, and says what semver bump the changes need. It exits 1 if anything is breaking, so it can run in CI on every pull request. The script cannot see behaviour changes such as a new default value, a different sort order, stricter server-side validation that the spec does not show, or new side effects. Ask about those directly. When there is only one version, write the breaking-change risk list from the lint instead. It lists the findings whose fix would itself be breaking (bare array lists, integer IDs, missing pagination, error shape, field renames), so the user knows what to fix before launch. ## 4. Write review.md Write `review.md` next to the API source unless the user says otherwise. Use this structure, and see `examples/review.md` for a full example: 1. **Summary.** Two or three sentences with the overall verdict and the top three fixes. 2. **Scorecard.** A table with each area from the reference.md rubric, a 0 to 3 score, and one line of reason. Mark areas that do not apply as n/a. 3. **Findings, ranked by severity (P0 to P3).** For each finding, give where it is, what is wrong, why it costs users something, the precedent from a public guideline, and a concrete rewrite (before and after for the path, schema, error body or call site). Group repeated cases into one finding with a list of locations. 4. **Breaking-change risk list.** Diff results if there were two versions. Otherwise, the fixes from the findings that would break clients, each with a migration path (alias, deprecation header, sunset date, new version). 5. **What's good.** Specific things the API does well, so the team keeps doing them. Write this section honestly and specifically, with no padding. 6. **Not checked.** What the review could not see. Keep findings concrete. "Errors are inconsistent" is not a finding. "`POST /orders` returns `{error: {msg}}` and `GET /orders/{id}` returns `{message}`, so clients need two error handlers" is a finding. ## 5. Hand over Show the user the summary and the top findings in chat, and give the path to `review.md`. If they want to fix things, start with the P0 findings, then the P1 findings that are breaking, and re-run the lint and the diff after each change.skills/coding/api-design-review/scripts/_spec.py11 KBa0858e94e473upstream ↗
"""Shared helpers: load an OpenAPI document (JSON or YAML) and resolve local $refs. Standard library only. If PyYAML is installed it is used for YAML files. Otherwise a small fallback parser handles the block-style YAML subset that OpenAPI files normally use (maps, lists, quoted and plain scalars, flow lists and maps on one line, | and > block strings, comments). Anchors, aliases, tags and multi-document files are not supported by the fallback; convert those files to JSON first. """ import json import re import sys HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace") # ---------------------------------------------------------------- loading def load_spec(path): with open(path, "r", encoding="utf-8") as fh: text = fh.read() stripped = text.lstrip() if stripped.startswith("{"): return json.loads(text) try: import yaml # type: ignore return yaml.safe_load(text) except ImportError: pass try: return MiniYaml(text).parse() except Exception as exc: # noqa: BLE001 sys.exit( "Could not parse %s as YAML without PyYAML (%s).\n" "Install PyYAML (pip install pyyaml) or convert the file to JSON." % (path, exc) ) class MiniYaml: """Minimal block-YAML parser, enough for typical OpenAPI files.""" def __init__(self, text): self.lines = [] raw = text.splitlines() i = 0 while i < len(raw): line = raw[i].rstrip() i += 1 if not line.strip() or line.strip().startswith("#") or line.strip() in ("---", "..."): continue indent = len(line) - len(line.lstrip(" ")) content = _strip_comment(line.strip()) self.lines.append([indent, content, i]) # keep raw lines of block scalars untouched if re.search(r":\s*[|>][-+]?$", content) or re.match(r"^-\s*[|>][-+]?$", content): block = [] while i < len(raw) and (not raw[i].strip() or len(raw[i]) - len(raw[i].lstrip(" ")) > indent): block.append(raw[i]) i += 1 self.lines[-1].append(block) def parse(self): if not self.lines: return None value, idx = self._block(0, self.lines[0][0]) if idx != len(self.lines): raise ValueError("unexpected indentation at line %d" % self.lines[idx][2]) return value def _block(self, idx, indent): if self.lines[idx][1].startswith("- ") or self.lines[idx][1] == "-": return self._list(idx, indent) return self._map(idx, indent) def _list(self, idx, indent): out = [] while idx < len(self.lines) and self.lines[idx][0] == indent and ( self.lines[idx][1].startswith("- ") or self.lines[idx][1] == "-"): entry = self.lines[idx] rest = entry[1][1:].strip() if not rest: idx += 1 if idx < len(self.lines) and self.lines[idx][0] > indent: val, idx = self._block(idx, self.lines[idx][0]) else: val = None out.append(val) elif _split_key(rest) is not None and not rest.startswith(("'", '"', "[", "{")): # "- key: value" starts a map indented at the key position offset = len(entry[1]) - len(rest) entry[0] = indent + offset entry[1] = rest val, idx = self._map(idx, indent + offset) out.append(val) elif len(entry) > 3: out.append(_block_scalar(rest, entry[3])) idx += 1 else: out.append(_scalar(rest)) idx += 1 return out, idx def _map(self, idx, indent): out = {} while idx < len(self.lines) and self.lines[idx][0] == indent: entry = self.lines[idx] if entry[1].startswith("- "): break kv = _split_key(entry[1]) if kv is None: raise ValueError("expected 'key: value' at line %d" % entry[2]) key, rest = kv idx += 1 if len(entry) > 3: out[key] = _block_scalar(rest, entry[3]) elif rest: out[key] = _scalar(rest) elif idx < len(self.lines) and self.lines[idx][0] > indent: out[key], idx = self._block(idx, self.lines[idx][0]) elif idx < len(self.lines) and self.lines[idx][0] == indent and \ self.lines[idx][1].startswith("-"): out[key], idx = self._list(idx, indent) else: out[key] = None return out, idx def _strip_comment(s): quote = None for i, ch in enumerate(s): if quote: if ch == quote: quote = None elif ch in ("'", '"'): quote = ch elif ch == "#" and (i == 0 or s[i - 1] in " \t"): return s[:i].rstrip() return s def _split_key(s): if s.startswith(("'", '"')): q = s[0] end = s.find(q, 1) if end == -1: return None key, after = s[1:end], s[end + 1:].lstrip() if not after.startswith(":"): return None return key, after[1:].strip() depth = 0 for i, ch in enumerate(s): if ch in "[{": depth += 1 elif ch in "]}": depth -= 1 elif ch == ":" and depth == 0 and (i + 1 == len(s) or s[i + 1] in " \t"): return s[:i].strip(), s[i + 1:].strip() return None def _block_scalar(indicator, raw_lines): lines = [l for l in raw_lines] nonblank = [l for l in lines if l.strip()] if not nonblank: return "" cut = min(len(l) - len(l.lstrip(" ")) for l in nonblank) body = [l[cut:] if l.strip() else "" for l in lines] while body and not body[-1]: body.pop() if indicator.startswith(">"): text = " ".join(x for x in body if x) else: text = "\n".join(body) return text if indicator.endswith("-") else text + "\n" def _scalar(s): s = s.strip() if s.startswith("[") and s.endswith("]"): inner = s[1:-1].strip() return [_scalar(x) for x in _split_flow(inner)] if inner else [] if s.startswith("{") and s.endswith("}"): inner = s[1:-1].strip() out = {} for part in _split_flow(inner) if inner else []: kv = _split_key(part) if kv is None: raise ValueError("bad flow map entry: %r" % part) out[kv[0]] = _scalar(kv[1]) if kv[1] else None return out if len(s) >= 2 and s[0] == s[-1] == '"': return json.loads(s) if len(s) >= 2 and s[0] == s[-1] == "'": return s[1:-1].replace("''", "'") low = s.lower() if low in ("true", "yes", "on"): return True if low == "true" else s if low == "false": return False if low in ("null", "~", ""): return None if re.match(r"^[-+]?\d+$", s): return int(s) if re.match(r"^[-+]?(\d+\.\d*|\.\d+|\d+)([eE][-+]?\d+)?$", s): return float(s) return s def _split_flow(s): parts, depth, quote, cur = [], 0, None, "" for ch in s: if quote: cur += ch if ch == quote: quote = None continue if ch in ("'", '"'): quote = ch elif ch in "[{": depth += 1 elif ch in "]}": depth -= 1 elif ch == "," and depth == 0: parts.append(cur.strip()) cur = "" continue cur += ch if cur.strip(): parts.append(cur.strip()) return parts # ---------------------------------------------------------------- $ref handling def resolve_pointer(doc, ref): if not ref.startswith("#/"): return None # external refs are not followed node = doc for part in ref[2:].split("/"): part = part.replace("~1", "/").replace("~0", "~") if isinstance(node, dict) and part in node: node = node[part] else: return None return node def deref(doc, node, seen=None): """Follow a single $ref chain (not recursive into children).""" seen = seen or set() while isinstance(node, dict) and "$ref" in node: ref = node["$ref"] if ref in seen: return {} seen.add(ref) target = resolve_pointer(doc, ref) if target is None: return node node = target return node def ref_name(node): if isinstance(node, dict) and isinstance(node.get("$ref"), str): return node["$ref"].rsplit("/", 1)[-1] return None def iter_operations(spec): """Yield (path, method, operation, path_item) with path-level params merged.""" for path, item in (spec.get("paths") or {}).items(): if not isinstance(item, dict): continue item = deref(spec, item) shared = item.get("parameters") or [] for method in HTTP_METHODS: op = item.get(method) if not isinstance(op, dict): continue yield path, method, op, shared def op_parameters(spec, op, shared): """Return resolved parameters, operation-level overriding path-level.""" merged = {} for p in list(shared) + list(op.get("parameters") or []): p = deref(spec, p) if isinstance(p, dict) and "name" in p: merged[(p.get("in"), p["name"].lower() if p.get("in") == "header" else p["name"])] = p return list(merged.values()) def schema_properties(spec, schema, depth=0, seen=None): """Flatten object properties (follows $ref, allOf). Returns dict name -> schema.""" seen = seen if seen is not None else set() out = {} if depth > 12 or not isinstance(schema, dict): return out name = ref_name(schema) if name: if name in seen: return out seen = seen | {name} schema = deref(spec, schema) for sub in schema.get("allOf") or []: out.update(schema_properties(spec, sub, depth + 1, seen)) for k, v in (schema.get("properties") or {}).items(): out[k] = v return out def json_content(spec, content): """Pick the JSON-ish media type from a content map.""" if not isinstance(content, dict): return None, None for mt, body in content.items(): if "json" in mt: return mt, body for mt, body in content.items(): return mt, body return None, Noneskills/coding/api-design-review/scripts/breaking_diff.py24 KBc94eec065f9aupstream ↗
#!/usr/bin/env python3 """Diff two OpenAPI 3.x documents and classify every change. Classes: BREAKING an existing, correctly written client can fail or misbehave. RISKY correct clients keep working, but clients that are strict (exhaustive enum switches, strict deserializers, status code checks) or generated SDKs may break. Decide case by case. SAFE additive or loosening change that tolerant clients absorb. The rules follow the request/response asymmetry: a request may get looser and a response may get richer, never the reverse. See reference.md for the reasoning and precedents (Google AIP-180, Stripe API upgrades, Zalando compatibility rules, Microsoft/Azure breaking change policy). Usage: python3 breaking_diff.py old.json new.yaml [--format text|md|json] [--no-fail] Exit code 1 when there is at least one BREAKING change (use in CI), unless --no-fail is given. """ import argparse import json import os import re import sys from collections import OrderedDict sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) from _spec import load_spec, deref, ref_name, iter_operations, op_parameters, json_content # noqa: E402 BREAKING, RISKY, SAFE = "BREAKING", "RISKY", "SAFE" CONSTRAINT_UPPER = ("maxLength", "maximum", "maxItems", "maxProperties", "exclusiveMaximum") CONSTRAINT_LOWER = ("minLength", "minimum", "minItems", "minProperties", "exclusiveMinimum") def norm_path(path): return re.sub(r"\{[^}]+\}", "{}", path) def stype(schema): t = schema.get("type") nullable = bool(schema.get("nullable")) if isinstance(t, list): nullable = nullable or "null" in t rest = [x for x in t if x != "null"] t = rest[0] if len(rest) == 1 else (",".join(sorted(rest)) or None) if t is None and "properties" in schema: t = "object" return t, nullable class Differ: def __init__(self, old, new): self.old, self.new = old, new self.changes = [] self.usage = OrderedDict() # "schema Name (direction)" -> [where it is used] def add(self, cls, where, what, why=""): self.changes.append(OrderedDict(cls=cls, where=where, change=what, why=why)) # ------------------------------------------------------------ schemas def schema(self, o, n, direction, where, seen=None, depth=0): """direction: 'request' (client sends) or 'response' (client reads).""" seen = seen or set() if depth > 25 or o is None or n is None: return key = (ref_name(o), ref_name(n)) if key != (None, None): if key in seen: return seen = seen | {key} if key[0] and key[0] == key[1]: label = "schema %s (%s)" % (key[0], direction) first = label not in self.usage self.usage.setdefault(label, []) if where not in self.usage[label]: self.usage[label].append(where) if not first: return where = label o, n = deref(self.old, o), deref(self.new, n) if not isinstance(o, dict) or not isinstance(n, dict): return req = direction == "request" ot, onull = stype(o) nt, nnull = stype(n) if ot and nt and ot != nt: widening = (ot, nt) == ("integer", "number") if req and widening: self.add(SAFE, where, "type widened integer -> number") elif not req and (ot, nt) == ("number", "integer"): self.add(SAFE, where, "type narrowed number -> integer") else: self.add(BREAKING, where, "type changed %s -> %s" % (ot, nt), "Clients serialize or parse this field with the old type.") return if o.get("format") != n.get("format") and (o.get("format") or n.get("format")): self.add(BREAKING if (o.get("format") and n.get("format")) or req else RISKY, where, "format changed %s -> %s" % (o.get("format"), n.get("format")), "Typed SDKs map formats to types (date-time to a datetime, int64 to a long).") if onull != nnull: if not req and nnull: self.add(BREAKING, where, "response field became nullable", "Clients that dereference it without a null check will crash.") elif req and not nnull: self.add(BREAKING, where, "request field no longer accepts null") else: self.add(SAFE, where, "nullability loosened" if req else "response field no longer null") # enums oe, ne = o.get("enum"), n.get("enum") if oe is not None and ne is not None: added = [v for v in ne if v not in oe] removed = [v for v in oe if v not in ne] if added: if req: self.add(SAFE, where, "enum values added: %s" % added) else: self.add(RISKY, where, "enum values added to a response: %s" % added, "Additive by most policies (Stripe, Google AIP-180), but clients " "with exhaustive switches or strict enum types will fail. Say so in " "the changelog and make sure SDKs have an 'unknown' fallback.") if removed: if req: self.add(BREAKING, where, "enum values removed from a request: %s" % removed, "Clients still send them and will now get errors.") else: self.add(SAFE, where, "enum values no longer returned: %s" % removed) elif oe is None and ne is not None: self.add(BREAKING if req else SAFE, where, "enum restriction added") elif oe is not None and ne is None: self.add(SAFE if req else RISKY, where, "enum restriction removed") # numeric and length constraints for k in CONSTRAINT_UPPER + CONSTRAINT_LOWER + ("pattern",): ov, nv = o.get(k), n.get(k) if ov == nv or isinstance(ov, bool) or isinstance(nv, bool): continue if k == "pattern": tighter = nv is not None elif k in CONSTRAINT_UPPER: tighter = nv is not None and (ov is None or nv < ov) else: tighter = nv is not None and (ov is None or nv > ov) if req: self.add(BREAKING if tighter else SAFE, where, "%s changed %s -> %s" % (k, ov, nv), "Values that were valid before are now rejected." if tighter else "") else: self.add(SAFE if tighter else RISKY, where, "%s changed %s -> %s" % (k, ov, nv), "" if tighter else "Clients may have sized buffers, columns or UI " "for the old limit.") # objects op_, np_ = o.get("properties") or {}, n.get("properties") or {} oreq, nreq = set(o.get("required") or []), set(n.get("required") or []) removed = [k for k in op_ if k not in np_] added = [k for k in np_ if k not in op_] for k in removed: hint = self.rename_hint(op_[k], np_, added, k) if req: self.add(BREAKING, "%s.%s" % (where, k), "request field removed" + hint, "Clients still send it. It will be rejected or, worse, silently " "ignored.") else: self.add(BREAKING, "%s.%s" % (where, k), "response field removed" + hint, "Clients that read it get nothing or crash.") for k in added: if req and k in nreq: self.add(BREAKING, "%s.%s" % (where, k), "new required request field", "Every existing call is missing it.") else: self.add(SAFE, "%s.%s" % (where, k), "new optional request field" if req else "new response field") for k in op_: if k not in np_: continue fw = "%s.%s" % (where, k) if req and k in nreq and k not in oreq: self.add(BREAKING, fw, "request field became required") elif req and k in oreq and k not in nreq: self.add(SAFE, fw, "request field became optional") elif not req and k in oreq and k not in nreq: self.add(BREAKING, fw, "response field no longer guaranteed (not required)", "Clients assume it is always present.") self.schema(op_[k], np_[k], direction, fw, seen, depth + 1) oa, na = o.get("additionalProperties"), n.get("additionalProperties") if req and oa is not False and na is False: self.add(BREAKING, where, "request object now rejects unknown fields") if isinstance(o.get("items"), dict) and isinstance(n.get("items"), dict): self.schema(o["items"], n["items"], direction, where + "[]", seen, depth + 1) for comb in ("oneOf", "anyOf"): ov, nv = o.get(comb) or [], n.get(comb) or [] if len(nv) > len(ov): self.add(SAFE if req else RISKY, where, "%s gained %d variant(s)" % (comb, len(nv) - len(ov)), "" if req else "Clients that switch on the variant may not handle it.") elif len(nv) < len(ov): self.add(BREAKING if req else SAFE, where, "%s lost %d variant(s)" % (comb, len(ov) - len(nv))) for i, (a, b) in enumerate(zip(o.get("allOf") or [], n.get("allOf") or [])): self.schema(a, b, direction, where, seen, depth + 1) def rename_hint(self, old_prop, new_props, added, old_name=None): ot = stype(deref(self.old, old_prop))[0] same = [a for a in added if stype(deref(self.new, new_props[a]))[0] == ot] if len(same) != 1: same = [a for a in added if old_name and (a.startswith(old_name) or old_name.startswith(a) or a.replace("_", "").lower() == old_name.replace("_", "").lower())] if len(same) == 1: return " (looks renamed to '%s'; keep the old name as a deprecated alias)" % same[0] return "" # ------------------------------------------------------------ operations def ops(self, spec): out = OrderedDict() for path, method, op, shared in iter_operations(spec): out[(method, norm_path(path))] = (path, op, shared) return out def run(self): self.global_changes() old_ops, new_ops = self.ops(self.old), self.ops(self.new) for key, (path, op, shared) in old_ops.items(): where = "%s %s" % (key[0].upper(), path) if key not in new_ops: self.add(BREAKING, where, "operation removed", "Deprecate first, announce a sunset date, then remove in a new " "major version.") continue npath, nop, nshared = new_ops[key] if npath != path: self.add(SAFE, where, "path parameter renamed: %s -> %s" % (path, npath), "Wire format unchanged; generated SDK argument names may change.") self.operation(where, op, shared, nop, nshared) for key, (path, op, shared) in new_ops.items(): if key not in old_ops: self.add(SAFE, "%s %s" % (key[0].upper(), path), "operation added") self.webhooks() return self.changes def global_changes(self): os_ = [s.get("url") for s in self.old.get("servers") or [] if isinstance(s, dict)] ns = [s.get("url") for s in self.new.get("servers") or [] if isinstance(s, dict)] for url in os_: if url not in ns: self.add(BREAKING, "servers", "server URL removed: %s" % url, "Clients have the base URL hard-coded.") oschemes = (self.old.get("components") or {}).get("securitySchemes") or {} nschemes = (self.new.get("components") or {}).get("securitySchemes") or {} for name, s in oschemes.items(): if name not in nschemes: self.add(BREAKING, "securitySchemes." + name, "security scheme removed") elif deref(self.old, s).get("type") != deref(self.new, nschemes[name]).get("type") or \ deref(self.old, s).get("in") != deref(self.new, nschemes[name]).get("in") or \ deref(self.old, s).get("name") != deref(self.new, nschemes[name]).get("name"): self.add(BREAKING, "securitySchemes." + name, "security scheme changed how " "credentials are sent") ov, nv = str((self.old.get("info") or {}).get("version", "")), \ str((self.new.get("info") or {}).get("version", "")) self.versions = (ov, nv) def operation(self, where, op, shared, nop, nshared): if op.get("operationId") and op.get("operationId") != nop.get("operationId"): self.add(BREAKING, where, "operationId changed %s -> %s" % (op.get("operationId"), nop.get("operationId")), "Wire format is unchanged, but generated SDK method names change.") if nop.get("deprecated") and not op.get("deprecated"): self.add(SAFE, where, "operation deprecated", "Good: also send Deprecation and Sunset headers (RFC 9745, RFC 8594).") # security osec = op.get("security", self.old.get("security")) or [] nsec = nop.get("security", self.new.get("security")) or [] if self.sec_set(osec) != self.sec_set(nsec): if not osec or osec == [{}]: self.add(BREAKING, where, "authentication now required", "Anonymous callers will get 401.") elif not nsec or nsec == [{}]: self.add(SAFE, where, "authentication no longer required") else: self.add(BREAKING, where, "security requirements changed: %s -> %s" % (sorted(self.sec_set(osec)), sorted(self.sec_set(nsec))), "Existing tokens may lack the new scheme or scope.") # parameters oparams = {(p.get("in"), p["name"]): p for p in op_parameters(self.old, op, shared)} nparams = {(p.get("in"), p["name"]): p for p in op_parameters(self.new, nop, nshared)} for k, p in oparams.items(): pw = "%s %s param '%s'" % (where, k[0], k[1]) if k not in nparams: if k[0] == "path": continue # covered by path rename moved = [nk for nk in nparams if nk[1] == k[1]] if moved: self.add(BREAKING, pw, "parameter moved from %s to %s" % (k[0], moved[0][0])) else: self.add(BREAKING if p.get("required") else RISKY, pw, "parameter removed", "Clients still send it and it will be ignored or rejected. If it " "changed behaviour (a filter, a flag), ignoring it silently is " "worse than an error.") continue np_ = nparams[k] if np_.get("required") and not p.get("required"): self.add(BREAKING, pw, "parameter became required") elif p.get("required") and not np_.get("required"): self.add(SAFE, pw, "parameter became optional") self.schema(p.get("schema"), np_.get("schema"), "request", pw) for k, p in nparams.items(): if k not in oparams and not any(ok[1] == k[1] for ok in oparams): pw = "%s %s param '%s'" % (where, k[0], k[1]) if p.get("required") and k[0] != "path": self.add(BREAKING, pw, "new required parameter", "Existing calls lack it.") elif k[0] != "path": self.add(SAFE, pw, "new optional parameter") # request body ob = deref(self.old, op.get("requestBody")) or {} nb = deref(self.new, nop.get("requestBody")) or {} if nb and not ob: self.add(BREAKING if nb.get("required") else SAFE, where + " body", "request body added" + (" and required" if nb.get("required") else "")) elif ob and not nb: self.add(BREAKING, where + " body", "request body removed") elif ob and nb: if nb.get("required") and not ob.get("required"): self.add(BREAKING, where + " body", "request body became required") self.content(ob.get("content") or {}, nb.get("content") or {}, "request", where + " body") # responses oresp, nresp = op.get("responses") or {}, nop.get("responses") or {} oc = {str(c) for c in oresp} nc = {str(c) for c in nresp} osucc = {c for c in oc if c.startswith("2")} nsucc = {c for c in nc if c.startswith("2")} for c in sorted(osucc - nsucc): self.add(BREAKING, where, "success status %s no longer returned (now %s)" % (c, ", ".join(sorted(nsucc)) or "none"), "Clients that check the exact status code will treat success as failure.") for c in sorted(nsucc - osucc): if osucc and osucc <= nsucc: self.add(RISKY, where, "new success status %s" % c) for c in sorted((nc - oc) - nsucc): self.add(RISKY, where, "new error status %s documented" % c, "Safe if this only documents existing behaviour. If the server now " "fails in a new way, clients need to handle it.") for c in sorted((oc - nc) - osucc): self.add(SAFE, where, "error status %s no longer documented" % c) for c in sorted(oc & nc): ro = deref(self.old, oresp.get(c, oresp.get(int(c)) if c.isdigit() else None)) or {} rn = deref(self.new, nresp.get(c, nresp.get(int(c)) if c.isdigit() else None)) or {} rw = "%s -> %s" % (where, c) self.content(ro.get("content") or {}, rn.get("content") or {}, "response", rw) oh = {h.lower() for h in ro.get("headers") or {}} nh = {h.lower() for h in rn.get("headers") or {}} for h in sorted(oh - nh): self.add(BREAKING, rw, "response header '%s' removed" % h) for h in sorted(nh - oh): self.add(SAFE, rw, "response header '%s' added" % h) def sec_set(self, sec): out = set() for req in sec or []: for name, scopes in (req or {}).items(): out.add((name, tuple(sorted(scopes or [])))) return frozenset(out) def content(self, oc, nc, direction, where): for mt in oc: if mt not in nc: self.add(BREAKING, where, "media type '%s' removed" % mt) for mt in nc: if mt not in oc: self.add(SAFE, where, "media type '%s' added" % mt) for mt in oc: if mt in nc: self.schema((oc[mt] or {}).get("schema"), (nc[mt] or {}).get("schema"), direction, where) def webhooks(self): oh, nh = self.old.get("webhooks") or {}, self.new.get("webhooks") or {} for name, item in oh.items(): where = "webhook " + name if name not in nh: self.add(BREAKING, where, "webhook event removed") continue for method, op in (item or {}).items(): nop = (nh[name] or {}).get(method) if not isinstance(op, dict) or not isinstance(nop, dict): continue ob = deref(self.old, op.get("requestBody")) or {} nb = deref(self.new, nop.get("requestBody")) or {} # the receiver reads the payload, so it follows response rules self.content(ob.get("content") or {}, nb.get("content") or {}, "response", where) for name in nh: if name not in oh: self.add(RISKY, "webhook " + name, "new webhook event type", "Receivers subscribed to all events must ignore unknown types; " "only safe if your docs promised that.") def semver_advice(changes, versions): has_b = any(c["cls"] == BREAKING for c in changes) has_new = any(c["cls"] in (SAFE, RISKY) for c in changes) need = "major" if has_b else ("minor" if has_new else "patch") ov, nv = versions note = "Changes need a %s version bump." % need try: om, nm = int(ov.split(".")[0]), int(nv.split(".")[0]) if has_b and nm <= om: note += " info.version went %s -> %s, which does not signal a breaking change." % (ov, nv) except ValueError: pass return note def render(changes, advice, fmt, a, b, usage): touched = OrderedDict() for label, wheres in usage.items(): if any(c["where"].startswith(label) for c in changes): touched[label] = wheres if fmt == "json": return json.dumps({"old": a, "new": b, "advice": advice, "changes": changes, "shared_schema_usage": touched}, indent=2) counts = {k: sum(1 for c in changes if c["cls"] == k) for k in (BREAKING, RISKY, SAFE)} lines = [] head = "%d breaking, %d risky, %d safe. %s" % (counts[BREAKING], counts[RISKY], counts[SAFE], advice) if fmt == "md": lines.append("# API diff: %s -> %s\n\n%s\n" % (os.path.basename(a), os.path.basename(b), head)) for cls in (BREAKING, RISKY, SAFE): items = [c for c in changes if c["cls"] == cls] if not items: continue lines.append("## %s (%d)\n" % (cls.title(), len(items))) for c in items: lines.append("- `%s`: %s%s" % (c["where"], c["change"], (". " + c["why"]) if c["why"] else "")) lines.append("") if touched: lines.append("## Where changed shared schemas are used\n") for label, wheres in touched.items(): lines.append("- `%s`: %s" % (label, ", ".join("`%s`" % w for w in wheres))) return "\n".join(lines) + "\n" lines.append("API diff: %s -> %s" % (a, b)) lines.append(head) for cls in (BREAKING, RISKY, SAFE): items = [c for c in changes if c["cls"] == cls] if not items: continue lines.append("") lines.append("%s (%d)" % (cls, len(items))) for c in items: lines.append(" %s: %s" % (c["where"], c["change"])) if c["why"]: lines.append(" " + c["why"]) if touched: lines.append("") lines.append("Where changed shared schemas are used") for label, wheres in touched.items(): lines.append(" %s: %s" % (label, "; ".join(wheres))) return "\n".join(lines) + "\n" def main(): ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) ap.add_argument("old") ap.add_argument("new") ap.add_argument("--format", choices=("text", "md", "json"), default="text") ap.add_argument("--no-fail", action="store_true", help="always exit 0") args = ap.parse_args() old, new = load_spec(args.old), load_spec(args.new) d = Differ(old, new) changes = d.run() # de-duplicate (shared schemas are reached from several operations) seen, unique = set(), [] for c in changes: k = (c["cls"], c["where"], c["change"]) if k not in seen: seen.add(k) unique.append(c) advice = semver_advice(unique, d.versions) sys.stdout.write(render(unique, advice, args.format, args.old, args.new, d.usage)) if not args.no_fail and any(c["cls"] == BREAKING for c in unique): sys.exit(1) if __name__ == "__main__": main()skills/coding/api-design-review/scripts/lint_openapi.py38 KBb8a0acf35d3dupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/coding/api-design-review/scripts/sdk_surface.py27 KBe4f88f23f7c3upstream ↗
#!/usr/bin/env python3 """Dump the public surface of a Python package or a TypeScript .d.ts file as a tree, with ergonomics hints, so a reviewer can judge the SDK as a whole. Usage: python3 sdk_surface.py <python.module.name> [--path DIR] [--depth 2] python3 sdk_surface.py path/to/index.d.ts options: --format text|json --no-hints --private Python: the module is imported (so its import side effects run; only point it at code you trust). "Public" means __all__ when defined, otherwise names without a leading underscore that are defined in the package itself. TypeScript: a lightweight parser reads exported functions, classes, interfaces, types, enums, consts and namespaces from a .d.ts file. It does not type-check and does not follow imports. Hints flag the patterns that most often hurt SDK users: boolean flag arguments, long positional parameter lists, mutable defaults, missing docstrings and type annotations, 'any' in TypeScript, optional parameters before required ones, timeouts that default to "wait forever", and exception classes with no common base. """ import argparse import importlib import inspect import json import os import pkgutil import re import sys import types from collections import Counter, OrderedDict # ====================================================================== Python class PySurface: def __init__(self, root_name, depth, include_private, hints): self.root_name = root_name self.depth = depth self.private = include_private self.want_hints = hints self.hints = [] self.stats = Counter() self.exceptions = [] def hint(self, where, kind, msg): if self.want_hints: self.hints.append(OrderedDict(where=where, kind=kind, hint=msg)) def public(self, name): return self.private or not name.startswith("_") def run(self): mod = importlib.import_module(self.root_name) tree = self.module(mod, 0) self.exception_hints() return tree def module(self, mod, level): self.stats["modules"] += 1 node = OrderedDict(kind="module", name=mod.__name__, doc=_first_line(mod.__doc__), members=[]) names = getattr(mod, "__all__", None) explicit = names is not None if names is None: names = sorted(n for n in vars(mod) if self.public(n)) for name in names: if not hasattr(mod, name): continue obj = getattr(mod, name) if isinstance(obj, types.ModuleType): continue home = getattr(obj, "__module__", None) if not explicit and home and not (home == mod.__name__ or home.startswith(self.root_name + ".") or home == self.root_name or home.lstrip("_") == mod.__name__.lstrip("_")): continue # re-exported from elsewhere (typing, os, ...) where = "%s.%s" % (mod.__name__, name) if inspect.isclass(obj): cnode = self.cls(obj, where) if obj.__name__ != name: cnode["name"] = "%s = %s" % (name, obj.__name__) node["members"].append(cnode) elif callable(obj): node["members"].append(self.func(obj, where, name)) else: self.stats["constants"] += 1 node["members"].append(OrderedDict(kind="const", name=name, type=type(obj).__name__, value=_short_repr(obj))) if hasattr(mod, "__path__") and level < self.depth: for info in sorted(pkgutil.iter_modules(mod.__path__), key=lambda i: i.name): if not self.public(info.name) or info.name in ("tests", "test"): continue full = "%s.%s" % (mod.__name__, info.name) try: sub = importlib.import_module(full) except Exception as exc: # noqa: BLE001 node["members"].append(OrderedDict(kind="module", name=full, error="import failed: %s" % exc)) continue node["members"].append(self.module(sub, level + 1)) return node def cls(self, c, where): self.stats["classes"] += 1 bases = [b.__name__ for b in c.__bases__ if b is not object] is_exc = issubclass(c, BaseException) if is_exc: self.exceptions.append(c) self.stats["exceptions"] += 1 node = OrderedDict(kind="exception" if is_exc else "class", name=c.__name__, bases=bases, doc=_first_line(c.__doc__), members=[]) if not c.__doc__ or (c.__doc__ and c.__doc__ == (c.__bases__[0].__doc__ if c.__bases__ else None)): self.stats["undocumented"] += 1 if not is_exc: self.hint(where, "no-docstring", "Public class has no docstring.") init = c.__dict__.get("__init__") if init is not None and callable(init): node["init"] = self.signature(init, where + ".__init__", "__init__", method=True) for name, raw in c.__dict__.items(): if name.startswith("_") and not self.private: continue mwhere = "%s.%s" % (where, name) if isinstance(raw, property): node["members"].append(OrderedDict(kind="property", name=name, readonly=raw.fset is None, type=_ann(_ret_ann(raw.fget)))) elif isinstance(raw, (staticmethod, classmethod)): f = raw.__func__ m = self.func(f, mwhere, name, method=isinstance(raw, classmethod)) m["kind"] = "staticmethod" if isinstance(raw, staticmethod) else "classmethod" node["members"].append(m) elif inspect.isfunction(raw) or inspect.ismethoddescriptor(raw) or \ inspect.isbuiltin(raw): node["members"].append(self.func(raw, mwhere, name, method=True)) elif not callable(raw): node["members"].append(OrderedDict(kind="attr", name=name, type=type(raw).__name__, value=_short_repr(raw))) return node def func(self, f, where, name, method=False): self.stats["methods" if method else "functions"] += 1 node = OrderedDict(kind="method" if method else "function", name=name, async_=inspect.iscoroutinefunction(f), doc=_first_line(getattr(f, "__doc__", None))) node.update(self.signature(f, where, name, method)) if not getattr(f, "__doc__", None): self.stats["undocumented"] += 1 self.hint(where, "no-docstring", "Public callable has no docstring.") if re.search(r"[a-z][A-Z]", name) and not name.startswith("_"): self.hint(where, "naming", "camelCase name in Python. PEP 8 uses snake_case " "for functions and methods.") return node def signature(self, f, where, name, method=False): try: sig = inspect.signature(f) except (TypeError, ValueError): return OrderedDict(sig="(...)") params = list(sig.parameters.values()) if method and params and params[0].name in ("self", "cls"): params = params[1:] positional = [p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)] annotated = sum(1 for p in params if p.annotation is not p.empty) + \ (1 if sig.return_annotation is not sig.empty else 0) self.stats["params"] += len(params) self.stats["annotated"] += annotated self.stats["annotation_slots"] += len(params) + (0 if name == "__init__" else 1) if len(positional) > 4: self.hint(where, "long-positional", "%d positional parameters (%s). Callers will pass them in the wrong order; " "make the optional ones keyword-only with '*'." % (len(positional), ", ".join(p.name for p in positional))) for p in positional: if isinstance(p.default, bool): self.hint(where, "bool-positional", "'%s=%s' is a boolean flag that can be passed by position, so call " "sites read as f(x, True). Make it keyword-only." % (p.name, p.default)) if isinstance(p.default, (list, dict, set)): self.hint(where, "mutable-default", "'%s' has a mutable default (%r), shared across calls." % (p.name, p.default)) for p in params: if p.name in ("timeout", "timeout_s", "timeout_seconds", "read_timeout") \ and p.default is None: self.hint(where, "no-default-timeout", "'%s' defaults to None, which usually means wait forever. A network " "SDK should ship a finite default timeout." % p.name) elif p.name.startswith("timeout") and type(p.default) is object: self.hint(where, "no-default-timeout", "'%s' defaults to a sentinel object, which usually means 'use the " "global socket default', and that is no timeout unless the caller " "set one. Calls can hang forever. Ship a finite default." % p.name) return OrderedDict(sig=_format_sig(sig, method)) def exception_hints(self): if len(self.exceptions) < 2: return roots = set() for e in self.exceptions: mine = [b for b in e.__mro__[1:] if b in self.exceptions] if not mine: roots.add(e.__name__) if len(roots) > 1: self.hint(self.root_name, "exception-roots", "Public exceptions have %d separate roots (%s). Users cannot catch " "'every error from this library' with one except clause. Give them one " "base class." % (len(roots), ", ".join(sorted(roots)))) def _first_line(doc): if not doc: return "" for line in doc.strip().splitlines(): if line.strip(): return line.strip()[:100] return "" def _short_repr(v): r = repr(v) return r if len(r) <= 60 else r[:57] + "..." def _ann(a): if a is None or a is inspect.Signature.empty: return "" if isinstance(a, type): return a.__name__ return str(a).replace("typing.", "") def _ret_ann(f): try: return inspect.signature(f).return_annotation except (TypeError, ValueError): return None def _format_sig(sig, method): params = list(sig.parameters.values()) if method and params and params[0].name in ("self", "cls"): params = params[1:] text = str(sig.replace(parameters=params)) text = re.sub(r" at 0x[0-9a-fA-F]+>", ">", text) # memory addresses change every run return text.replace("typing.", "") def render_py(node, indent=0): pad = " " * indent out = [] k = node["kind"] if k == "module": out.append("%smodule %s%s" % (pad, node["name"], (" # " + node["doc"]) if node.get("doc") else (" # " + node["error"] if node.get("error") else ""))) for m in node.get("members", []): out.extend(render_py(m, indent + 1)) elif k in ("class", "exception"): bases = "(%s)" % ", ".join(node["bases"]) if node["bases"] else "" init = node.get("init", {}).get("sig", "") out.append("%s%s %s%s%s%s" % (pad, k, node["name"], bases, init, (" # " + node["doc"]) if node.get("doc") else "")) for m in node["members"]: out.extend(render_py(m, indent + 1)) elif k in ("function", "method", "staticmethod", "classmethod"): prefix = {"function": "def", "method": "def", "staticmethod": "@staticmethod def", "classmethod": "@classmethod def"}[k] if node.get("async_"): prefix = "async " + prefix out.append("%s%s %s%s" % (pad, prefix, node["name"], node.get("sig", "(...)"))) elif k == "property": out.append("%sproperty %s%s%s" % (pad, node["name"], (": " + node["type"]) if node["type"] else "", " (read-only)" if node["readonly"] else "")) elif k in ("const", "attr"): out.append("%s%s: %s = %s" % (pad, node["name"], node["type"], node["value"])) return out # ================================================================== TypeScript DECL_RE = re.compile( r"^(export\s+)?(declare\s+)?(default\s+)?(abstract\s+)?(async\s+)?" r"(function|class|interface|type|const|let|var|enum|namespace|module)\s+" r"([\w$.'\"]+)") class TsSurface: def __init__(self, hints): self.want_hints = hints self.hints = [] self.stats = Counter() def hint(self, where, kind, msg): if self.want_hints: self.hints.append(OrderedDict(where=where, kind=kind, hint=msg)) def run(self, path): with open(path, "r", encoding="utf-8") as fh: src = fh.read() src = re.sub(r"/\*\*(.*?)\*/", lambda m: " @@JSDOC@@ ", src, flags=re.S) src = re.sub(r"/\*.*?\*/", " ", src, flags=re.S) src = re.sub(r"(?m)//.*$", "", src) tree = OrderedDict(kind="module", name=os.path.basename(path), members=self.block(src, os.path.basename(path), top=True)) errors = [m for m in tree["members"] if m["kind"] == "class" and m["name"].endswith("Error")] roots = [m["name"] for m in errors if not any( e["name"] in (m.get("heritage") or "") for e in errors if e is not m)] if len(roots) > 1: self.hint(tree["name"], "exception-roots", "Error classes have %d separate roots (%s). Users cannot catch every SDK " "error with one instanceof check. Give them one base class." % (len(roots), ", ".join(roots))) return tree def statements(self, src): out, cur, depth, i = [], "", 0, 0 n = len(src) while i < n: ch = src[i] if ch in "'\"`": end = i + 1 while end < n and src[end] != ch: end += 2 if src[end] == "\\" else 1 cur += src[i:end + 1] i = end + 1 continue cur += ch if ch in "{([": depth += 1 elif ch in "})]": depth -= 1 if depth == 0 and ch == "}": head = cur.strip().replace("@@JSDOC@@", "").strip() if not re.match(r"^(export\s+)?(declare\s+)?(type|const|let|var|default\s*\{|=)", head): out.append(cur.strip()) cur = "" elif ch == ";" and depth == 0: out.append(cur.strip()) cur = "" elif ch == "\n" and depth == 0 and re.search(r"[\w)\]>]\s*$", cur.strip() or "{") \ and re.match(r"\s*(export|declare|@@JSDOC@@|interface|class|function|type|" r"const|enum|namespace)\b", src[i + 1:i + 40]): out.append(cur.strip()) cur = "" i += 1 if cur.strip(): out.append(cur.strip()) return [s for s in out if s and s != ";"] def block(self, src, scope, top=False): members = [] for stmt in self.statements(src): documented = stmt.lstrip().startswith("@@JSDOC@@") while stmt.lstrip().startswith("@@JSDOC@@"): stmt = stmt.lstrip()[len("@@JSDOC@@"):] stmt = stmt.strip().rstrip(";").strip() if not stmt: continue if re.match(r"^export\s*(\*|\{)", stmt): members.append(OrderedDict(kind="re-export", text=re.sub(r"\s+", " ", stmt))) continue m = DECL_RE.match(stmt) if not m: continue exported = bool(m.group(1)) or not top or stmt.startswith("declare") if not exported: continue kind, name = m.group(6), m.group(7).strip("'\"") where = "%s.%s" % (scope, name) if not top else name node = OrderedDict(kind=kind, name=name) if kind not in ("namespace", "module"): self.stats["declarations"] += 1 if documented: self.stats["documented"] += 1 else: self.hint(where, "no-docs", "Exported %s has no JSDoc comment." % kind) if kind == "function": sig = stmt[m.end():].strip() node["sig"] = _squash(sig) self.stats["functions"] += 1 self.check_params(where, sig) elif kind in ("class", "interface"): head, body = _split_body(stmt[m.end():]) node["heritage"] = _squash(head) node["members"] = self.members(body, where, kind) self.stats[kind + "es" if kind == "class" else kind + "s"] += 1 elif kind in ("namespace", "module"): _, body = _split_body(stmt[m.end():]) node["members"] = self.block(body, where) elif kind == "enum": _, body = _split_body(stmt[m.end():]) node["values"] = [v.split("=")[0].strip() for v in body.split(",") if v.strip()] else: node["sig"] = _squash(stmt[m.end():])[:160] if kind == "type" and re.search(r"\bany\b", stmt): self.hint(where, "any", "Type uses 'any', which turns off checking for users.") members.append(node) return members def members(self, body, where, kind): out = [] carry = False for raw in _split_top(body, ";\n"): documented = "@@JSDOC@@" in raw or carry line = raw.replace("@@JSDOC@@", "").strip().rstrip(",;").strip() carry = documented and not line if not line or line.startswith(("private ", "#")) or re.match(r"^(static\s+)?private\b", line): continue mods = re.match(r"^((public|protected|readonly|static|abstract|declare|override|async)\s+)*", line) modtext = mods.group(0) if mods else "" rest = line[len(modtext):] mwhere = "%s.%s" % (where, re.split(r"[(:<?\s]", rest, 1)[0]) mm = re.match(r"^(get\s+|set\s+)?(new\s*|[\w$]+|\[[^\]]+\])?(\??)\s*(<[^(]*>)?\s*\(", rest) if mm and (mm.group(2) or rest.startswith("(")): self.stats["methods"] += 1 if not documented and kind == "class": self.hint(mwhere, "no-docs", "Public method has no JSDoc comment.") out.append(OrderedDict(kind="method", text=_squash(modtext + rest))) self.check_params(mwhere, rest[rest.index("("):]) else: self.stats["properties"] += 1 out.append(OrderedDict(kind="property", text=_squash(modtext + rest))) if re.search(r":\s*any\b", rest): self.hint(mwhere, "any", "Property typed 'any'.") return out def check_params(self, where, sig): if not sig.startswith("(") and "(" in sig: sig = sig[sig.index("("):] if not sig.startswith("("): return depth, end = 0, 0 for i, ch in enumerate(sig): depth += ch in "({[<" depth -= ch in ")}]>" and not (ch == ">" and i and sig[i - 1] == "=") if depth == 0: end = i break params = [p.strip() for p in _split_top(sig[1:end], ",") if p.strip()] ret = sig[end + 1:].strip().lstrip(":").strip() if len(params) > 4: self.hint(where, "long-positional", "%d positional parameters. Group the optional " "ones into an options object." % len(params)) seen_optional = False for p in params: name = re.split(r"[?:=]", p, 1)[0].strip() optional = "?" in p.split(":")[0] or "=" in p if optional: seen_optional = True elif seen_optional and not p.startswith("..."): self.hint(where, "optional-before-required", "Required parameter '%s' comes after an optional one." % name) if re.search(r":\s*boolean\s*$", p): self.hint(where, "bool-positional", "'%s: boolean' is a positional flag, so call sites read as f(x, true). " "Use an options object." % name) if re.search(r":\s*any\b", p): self.hint(where, "any", "Parameter '%s' is typed 'any'." % name) if re.match(r"timeout", name, re.I) is None and "callback" in name.lower(): self.hint(where, "callback", "Callback parameter '%s'. Modern TS SDKs return " "Promises." % name) if re.match(r"any\b", ret): self.hint(where, "any", "Returns 'any'.") def _squash(s): return re.sub(r"\s+", " ", s).strip() def _split_body(s): depth = 0 for i, ch in enumerate(s): if ch in "(<[": depth += 1 elif ch in ")>]" and not (ch == ">" and i and s[i - 1] == "="): depth -= 1 elif ch == "{" and depth == 0: close = _match_brace(s, i) return s[:i], s[i + 1:close] return s, "" def _match_brace(s, start): depth = 0 for i in range(start, len(s)): if s[i] == "{": depth += 1 elif s[i] == "}": depth -= 1 if depth == 0: return i return len(s) def _split_top(s, seps): out, cur, depth = [], "", 0 for i, ch in enumerate(s): if ch in "({[<": depth += 1 elif ch in ")}]>" and not (ch == ">" and i and s[i - 1] == "="): depth -= 1 if ch in seps and depth == 0: out.append(cur) cur = "" continue cur += ch out.append(cur) return out def render_ts(node, indent=0): pad = " " * indent out = [] k = node["kind"] if k == "module": out.append("%smodule %s" % (pad, node["name"])) for m in node["members"]: out.extend(render_ts(m, indent + 1)) elif k in ("class", "interface"): out.append("%s%s %s%s" % (pad, k, node["name"], (" " + node["heritage"]) if node.get("heritage") else "")) for m in node["members"]: out.append("%s %s %s" % (pad, "fn " if m["kind"] == "method" else "prop", m["text"])) elif k in ("namespace", "module"): out.append("%snamespace %s" % (pad, node["name"])) for m in node["members"]: out.extend(render_ts(m, indent + 1)) elif k == "enum": out.append("%senum %s { %s }" % (pad, node["name"], ", ".join(node["values"]))) elif k == "re-export": out.append("%s%s" % (pad, node["text"])) else: out.append("%s%s %s %s" % (pad, k, node["name"], node.get("sig", ""))) return out # ======================================================================== main def summary_lines(stats, kind): if kind == "py": slots = stats["annotation_slots"] or 1 callables = stats["functions"] + stats["methods"] + stats["classes"] return ["%d modules, %d classes (%d exceptions), %d functions, %d methods, %d constants." % (stats["modules"], stats["classes"], stats["exceptions"], stats["functions"], stats["methods"], stats["constants"]), "Docstrings on %d%% of public classes and callables. Type annotations on %d%% " "of parameter and return slots." % (100 - (100 * stats["undocumented"] // (callables or 1)), 100 * stats["annotated"] // slots)] total = stats["declarations"] or 1 return ["%d exported declarations (%d functions, %d classes, %d interfaces), %d members " "(%d methods, %d properties)." % (stats["declarations"], stats["functions"], stats["classes"], stats["interfaces"], stats["methods"] + stats["properties"], stats["methods"], stats["properties"]), "JSDoc on %d%% of exported declarations." % (100 * stats["documented"] // total)] def main(): ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) ap.add_argument("target", help="Python module name (e.g. 'json') or a .d.ts file") ap.add_argument("--path", help="directory to add to sys.path before importing") ap.add_argument("--depth", type=int, default=2, help="submodule depth for packages") ap.add_argument("--format", choices=("text", "json"), default="text") ap.add_argument("--no-hints", action="store_true") ap.add_argument("--private", action="store_true", help="include _private names") args = ap.parse_args() if args.target.endswith(".ts"): surf = TsSurface(not args.no_hints) tree = surf.run(args.target) lines = render_ts(tree) kind = "ts" else: if args.path: sys.path.insert(0, os.path.abspath(args.path)) surf = PySurface(args.target, args.depth, args.private, not args.no_hints) tree = surf.run() lines = render_py(tree) kind = "py" if args.format == "json": print(json.dumps({"tree": tree, "stats": dict(surf.stats), "hints": surf.hints}, indent=2, default=str)) return print("\n".join(lines)) print("") print("Summary") for line in summary_lines(surf.stats, kind): print(" " + line) if surf.hints: by_kind = Counter(h["kind"] for h in surf.hints) print("") print("Hints (%s)" % ", ".join("%d %s" % (n, k) for k, n in by_kind.most_common())) quiet = ("no-docstring", "no-docs") for h in surf.hints: if h["kind"] not in quiet: print(" [%s] %s: %s" % (h["kind"], h["where"], h["hint"])) undocumented = [h["where"] for h in surf.hints if h["kind"] in quiet] if undocumented: print(" [docs] %d public names have no doc comment, for example: %s%s" % ( len(undocumented), ", ".join(undocumented[:8]), " (use --format json for the full list)" if len(undocumented) > 8 else "")) if __name__ == "__main__": main()skills/coding/api-design-review/examples/bookshop-v1.json10.0 KBfe581d09cc00upstream ↗
{ "openapi": "3.1.0", "info": { "title": "Bookshop Orders API (deliberately flawed sample)", "version": "1.4.0", "description": "A fictional API with common design mistakes planted on purpose, used to test the api-design-review scripts." }, "servers": [{ "url": "https://api.bookshop.example/v1" }], "security": [{ "bearerAuth": [] }], "paths": { "/getCustomers": { "get": { "operationId": "getCustomers", "summary": "List customers", "responses": { "200": { "description": "All customers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } } } } }, "/customer/{customerId}": { "parameters": [{ "name": "customerId", "in": "path", "required": true, "schema": { "type": "integer" } }], "get": { "operationId": "getCustomer", "responses": { "200": { "description": "A customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad input" } } } }, "/orders": { "get": { "operationId": "listOrders", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/OrderStatus" } }, { "name": "customerId", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Every order", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewOrder" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Slow down", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{order_id}": { "parameters": [{ "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "operationId": "getOrder", "responses": { "200": { "description": "An order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateOrder", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["shippingAddress", "notes"], "properties": { "shippingAddress": { "type": "string", "maxLength": 500 }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } }, "delete": { "operationId": "getOrder", "responses": { "204": { "description": "Deleted" } } } }, "/orders/{order_id}/items": { "parameters": [{ "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "operationId": "listOrderItems", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "has_more": { "type": "boolean" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{order_id}/refund": { "parameters": [{ "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }], "post": { "operationId": "refundOrder", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } } }, "/payments": { "post": { "operationId": "createPayment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "402": { "description": "Card declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/shippingLabels/{label_id}": { "get": { "operationId": "getShippingLabel", "parameters": [{ "name": "label_id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Label PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/health": { "get": { "operationId": "health", "security": [], "responses": { "200": { "description": "OK" } } } } }, "webhooks": { "order.shipped": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "order": { "$ref": "#/components/schemas/Order" } } } } } }, "responses": { "200": { "description": "Acknowledged" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Customer": { "type": "object", "required": ["id", "email"], "properties": { "id": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "full_name": { "type": "string" }, "nickname": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "OrderStatus": { "type": "string", "enum": ["pending", "Shipped", "CANCELLED"] }, "Order": { "type": "object", "required": ["id", "customer_id", "status", "total", "created_at"], "properties": { "id": { "type": "string" }, "customer_id": { "type": "integer" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "total": { "type": "number", "format": "double" }, "currency": { "type": "string" }, "shippingAddress": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updatedDate": { "type": "string" }, "shipped": { "type": "integer", "description": "Unix seconds" } } }, "NewOrder": { "type": "object", "required": ["customer_id", "items"], "properties": { "customer_id": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "notes": { "type": "string", "maxLength": 1000 } } }, "OrderItem": { "type": "object", "properties": { "isbn": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "unitPrice": { "type": "number" } } }, "Payment": { "type": "object", "required": ["order_id", "amount"], "properties": { "id": { "type": "string", "readOnly": true }, "order_id": { "type": "string" }, "amount": { "type": "number" }, "card_token": { "type": "string" } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer" } } } } } } } }skills/coding/api-design-review/examples/bookshop-v2.yaml10.0 KB5174c426f014upstream ↗
# v2 of the deliberately flawed sample. Some changes fix v1 problems, # some quietly break existing clients. breaking_diff.py should tell them apart. openapi: 3.1.0 info: title: Bookshop Orders API (deliberately flawed sample) version: 1.5.0 # minor bump, although several changes below are breaking description: > Version two of the fictional sample API. servers: - url: https://api.bookshop.example/v1 security: - bearerAuth: [] paths: /customers: get: operationId: listCustomers parameters: - name: limit in: query schema: {type: integer, default: 20, maximum: 100} - name: starting_after in: query schema: {type: string} responses: '200': description: A page of customers content: application/json: schema: type: object properties: data: type: array items: {$ref: '#/components/schemas/Customer'} has_more: {type: boolean} default: $ref: '#/components/responses/Problem' /customer/{customerId}: parameters: - name: customerId in: path required: true schema: {type: string} get: operationId: getCustomer responses: '200': description: A customer content: application/json: schema: {$ref: '#/components/schemas/Customer'} '404': description: Not found content: application/json: schema: {$ref: '#/components/schemas/Error'} put: operationId: updateCustomer requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/Customer'} responses: '200': description: Updated content: application/json: schema: {$ref: '#/components/schemas/Customer'} '400': description: Bad input /orders: get: operationId: listOrders parameters: - name: status in: query schema: {$ref: '#/components/schemas/OrderStatus'} - name: limit in: query schema: {type: integer, default: 20, maximum: 100} - name: starting_after in: query schema: {type: string} responses: '200': description: A page of orders content: application/json: schema: type: object properties: data: type: array items: {$ref: '#/components/schemas/Order'} has_more: {type: boolean} '401': description: Unauthorized content: application/json: schema: {$ref: '#/components/schemas/Error'} post: operationId: createOrder parameters: - name: Idempotency-Key in: header required: false schema: {type: string, maxLength: 255} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/NewOrder'} responses: '201': description: Created content: application/json: schema: {$ref: '#/components/schemas/Order'} '400': description: Invalid content: application/json: schema: {$ref: '#/components/schemas/Error'} '429': description: Slow down headers: Retry-After: schema: {type: integer} content: application/json: schema: {$ref: '#/components/schemas/Error'} /orders/{id}: parameters: - name: id in: path required: true schema: {type: string} get: operationId: getOrder responses: '200': description: An order content: application/json: schema: {$ref: '#/components/schemas/Order'} '404': description: Not found content: application/json: schema: {$ref: '#/components/schemas/Error'} patch: operationId: updateOrder requestBody: content: application/json: schema: type: object properties: shippingAddress: {type: string, maxLength: 200} notes: {type: string} responses: '200': description: Updated content: application/json: schema: {$ref: '#/components/schemas/Order'} delete: operationId: deleteOrder deprecated: true responses: '204': description: Deleted /orders/{order_id}/items: parameters: - name: order_id in: path required: true schema: {type: string} get: operationId: listOrderItems parameters: - name: page in: query schema: {type: integer, default: 1} - name: per_page in: query schema: {type: integer, default: 20, maximum: 100} responses: '200': description: Items content: application/json: schema: type: object properties: data: type: array items: {$ref: '#/components/schemas/OrderItem'} has_more: {type: boolean} '404': description: Not found content: application/json: schema: {$ref: '#/components/schemas/Error'} /orders/{order_id}/refund: parameters: - name: order_id in: path required: true schema: {type: string} post: operationId: refundOrder requestBody: content: application/json: schema: type: object properties: amount: {type: integer} reason: type: string enum: [duplicate, fraudulent, requested_by_customer] responses: '200': description: Refunded content: application/json: schema: {$ref: '#/components/schemas/Order'} /payments: post: operationId: createPayment requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/Payment'} responses: '201': description: Payment content: application/json: schema: {$ref: '#/components/schemas/Payment'} '402': description: Card declined content: application/json: schema: {$ref: '#/components/schemas/Error'} /shippingLabels/{label_id}: get: operationId: getShippingLabel parameters: - name: label_id in: path required: true schema: {type: string} responses: '200': description: Label PDF content: application/pdf: schema: {type: string, format: binary} /health: get: operationId: health responses: '200': description: OK webhooks: order.shipped: post: parameters: - name: Webhook-Signature in: header required: true schema: {type: string} requestBody: content: application/json: schema: type: object properties: id: {type: string} type: {type: string} created_at: {type: string, format: date-time} order: {$ref: '#/components/schemas/Order'} responses: '200': description: Acknowledged components: securitySchemes: bearerAuth: type: http scheme: bearer responses: Problem: description: Error content: application/problem+json: schema: {$ref: '#/components/schemas/Error'} schemas: Customer: type: object required: [id, email] properties: id: {type: string} email: {type: string, format: email} full_name: {type: string} created_at: {type: string, format: date-time} OrderStatus: type: string enum: [pending, Shipped, CANCELLED, refunded] Order: type: object required: [id, customer_id, status, created_at] properties: id: {type: string} customer_id: {type: string} status: {$ref: '#/components/schemas/OrderStatus'} total_amount: {type: integer, description: 'Minor units, for example 1999 for 19.99'} currency: {type: string} shippingAddress: {type: [string, 'null']} created_at: {type: string, format: date-time} updatedDate: {type: string} shipped: {type: integer, description: Unix seconds} NewOrder: type: object required: [customer_id, items, currency] properties: customer_id: {type: string} items: type: array items: {$ref: '#/components/schemas/OrderItem'} notes: {type: string, maxLength: 1000} currency: {type: string, pattern: '^[A-Z]{3}$'} OrderItem: type: object properties: isbn: {type: string} quantity: {type: integer, minimum: 1} unitPrice: {type: number} Payment: type: object required: [order_id, amount] properties: id: {type: string, readOnly: true} order_id: {type: string} amount: {type: number} card_token: {type: string} Error: type: object required: [type, title, status, code, request_id] properties: type: {type: string, format: uri} title: {type: string} status: {type: integer} detail: {type: string} code: {type: string} request_id: {type: string}skills/coding/api-design-review/examples/review.md17 KBebd887748d1eupstream ↗
# API design review: Bookshop Orders API v1.4.0 This review covers `bookshop-v1.json`, the proposed `bookshop-v2.yaml`, and the TypeScript SDK surface in `sample-sdk.d.ts`. The Bookshop API is fictional and was written with planted mistakes to test this skill. The raw tool output is in `out/`, and this review was written from that output plus a manual read of the spec. The API is assumed to be public, with paying customers on v1. ## Summary The API is not ready for more public users, because two flaws can cost customers money and several others are breaking to fix. A retried `POST /payments` or `POST /orders/{order_id}/refund` can charge or refund twice, because neither accepts an idempotency key, and webhooks are unsigned, so anyone can fake an `order.shipped` event. The proposed v2 fixes some of these, but it also ships 24 breaking changes under a minor version number (1.4.0 to 1.5.0), so every existing integration would break without warning. The top fixes are listed below: 1. Add `Idempotency-Key` to every POST that creates something or moves money, and sign webhooks. 2. Ship v2's breaking changes as a new major version with a migration guide, or make them additive (keep old fields as deprecated aliases). 3. Settle one error schema, one ID type (string), one money format (integer minor units plus currency) and one list envelope with cursor pagination, before more clients depend on the current shapes. ## Scorecard | Area | Score | Reason | |---|---|---| | Naming and consistency | 1 | snake_case fields with seven camelCase exceptions, a verb path (`/getCustomers`), a singular collection (`/customer/{customerId}`) and camelCase path segments | | Resource modelling | 2 | Orders, items and payments are clear resources, but refund is an action that returns the Order instead of a Refund resource | | Errors | 0 | Two error shapes, neither has a machine code or request id, and six operations document no errors at all | | Evolution and versioning | 1 | URL version `/v1` exists, but v2 shows no compatibility rules, and the version number does not signal breaking changes | | Pagination, filtering, sorting | 0 | Two of three list endpoints return everything as a bare array, and the third uses page numbers | | Reliability | 0 | No idempotency anywhere, and the one 429 has no Retry-After | | Long-running operations | n/a | None in this API | | Webhooks | 0 | Unsigned, no event id, no event type field, no creation time | | Auth ergonomics | 2 | Bearer tokens in the Authorization header, with `/health` correctly public, but 401 and 403 are documented on only one operation | | Data formats | 0 | IDs are integers and strings, timestamps come in three formats, and money is a float in four places | | SDK ergonomics | 1 | Promise-based with a raw `request` escape hatch, but long positional arguments, boolean flags, a callback method, `any` types and two unrelated error roots | | CLI conventions | n/a | No CLI | ## Findings ### P0: Payments and refunds can run twice **Where:** `POST /payments`, `POST /orders/{order_id}/refund` (also `POST /orders`, as P1). If the response to `POST /payments` is lost (timeout, dropped connection, deploy), the client cannot tell whether the payment happened. A retry may charge the customer a second time, and not retrying may lose the order. Stripe solves this with an `Idempotency-Key` header, which the IETF is standardising in the draft "The Idempotency-Key HTTP Header Field". Google uses a `request_id` field (AIP-155) and Azure uses `Repeatability-Request-ID`. Before: ``` POST /payments {"order_id": "ord_1", "amount": 19.99} ``` After: ``` POST /payments Idempotency-Key: 3f8c6b1e-9a2d-4a57-8c51-0b6f8d9e2a11 {"order_id": "ord_1", "amount": 1999, "currency": "EUR"} ``` The server stores the key with the first response for at least 24 hours and returns that stored response on a retry. If the same key arrives with a different body, the server returns 422. The SDK generates a key per call and reuses it across its own retries. Adding an optional header is not breaking. ### P0: Webhooks are unsigned **Where:** `webhooks.order.shipped`. Any server on the internet can POST a fake `order.shipped` event to a receiver's endpoint, and a receiver that ships goods or sends emails on that event will act on it. The payload also has no event `id` to drop duplicates, no `type`, and no creation time to order events by. After: ``` POST <receiver URL> webhook-id: evt_2Lk9 webhook-timestamp: 1762611780 webhook-signature: v1,<base64 HMAC-SHA256 of "evt_2Lk9.1762611780.<raw body>"> {"id": "evt_2Lk9", "type": "order.shipped", "created_at": "2026-11-08T14:03:00Z", "data": {"order_id": "ord_1"}} ``` This follows the Standard Webhooks spec. Stripe's `Stripe-Signature` header works the same way. Tell receivers to reject timestamps older than five minutes, to drop duplicate ids, and to fetch the order rather than trust a possibly stale copy in the event, because delivery order is not guaranteed. Changing the payload is breaking for current receivers, so send the new shape as a new event version and run both during a migration window. ### P1: List endpoints return everything, as a bare array **Where:** `GET /orders`, `GET /getCustomers`. Both endpoints return every record in one JSON array. Response time and memory grow with the data until the calls time out, and a top-level array cannot gain a `has_more` or cursor field later without breaking every client. The guidelines agree on this point. Stripe, Google (AIP-158), Microsoft and Zalando all wrap lists in an object, and Zalando prefers cursors over offsets. Before: ``` GET /orders -> [ {...}, {...}, ... ] ``` After: ``` GET /orders?limit=50&starting_after=ord_8Fk2 -> {"data": [...], "has_more": true, "next_cursor": "ord_9Lm3"} ``` Document the default page size (e.g. 20) and the maximum (100). `GET /orders/{order_id}/items` already has the right envelope, but it uses `page`, which skips or repeats items when the list changes between pages. An order's items rarely change, so page numbers are acceptable there (P3). ### P1: Errors have no machine-readable code and two shapes **Where:** schema `Error` (`{message}`, 5 responses) and schema `ErrorResponse` (`{error: {msg, status}}`, 2 responses), plus six operations with no documented error at all (`DELETE /orders/{order_id}`, `GET /getCustomers`, `GET /health`, `GET /shippingLabels/{label_id}`, `PATCH /orders/{order_id}`, `POST /orders/{order_id}/refund`). Clients that need to react to an error (e.g. a declined card on `POST /payments`, versus out of stock on `POST /orders`) can only match on message text. After that, nobody can reword a message without breaking someone. Two shapes also mean two error handlers in every client. After (RFC 9457 problem details, used for every 4xx and 5xx): ``` HTTP/1.1 402 Payment Required Content-Type: application/problem+json Request-Id: req_7Hq2LmX {"type": "https://docs.bookshop.example/errors/card-declined", "title": "Card declined", "status": 402, "detail": "The card was declined by the issuer. Ask the customer for another card.", "code": "card_declined", "request_id": "req_7Hq2LmX"} ``` Migration: add `code`, `type` and `request_id` to both existing shapes now, which is additive. Keep `message` populated in `Error` (and `error.msg` in `ErrorResponse`) as deprecated fields until the next major version. The proposed v2 drops `message` outright, which the diff flags as breaking. ### P1: IDs are integers in some places and strings in others **Where:** `Customer.id`, `Order.customer_id`, `NewOrder.customer_id` and the `{customerId}` path parameter are integers. `Order.id`, `Payment.id` and `Payment.order_id` are strings. Clients have to remember which kind each ID is. Customer IDs above 2^53 will be corrupted by JavaScript clients, and sequential customer IDs reveal how many customers the shop has. Use opaque strings everywhere, ideally prefixed (`cus_`, `ord_`) as Stripe does, so a support engineer can tell an order ID from a customer ID. Changing a type is breaking. Do it in the next major version, or add `customer_ref` as a string now and deprecate the integer field. ### P1: Money is a floating point number **Where:** `Order.total` (double), `OrderItem.unitPrice`, `Payment.amount`, and the refund `amount` (float). `OrderItem.unitPrice`, `Payment.amount` and the refund `amount` have no currency. Floats cannot represent 0.10 exactly, so clients in different languages round differently, and totals stop matching line items. An amount with no currency is ambiguous once a second currency exists. After: ```json {"total_amount": 1999, "currency": "EUR"} ``` This uses integer minor units like Stripe. Zalando's money object and Google's Money type are decimal alternatives. Add the new fields alongside the old ones, and deprecate the float fields. ### P1: Duplicate operationId breaks generated SDKs **Where:** `GET /orders/{order_id}` and `DELETE /orders/{order_id}` are both `getOrder`. Code generators either fail or silently produce one method that hides the other. Rename the DELETE to `deleteOrder`. Renaming an operationId changes generated method names, so it counts as breaking for SDK users (the diff reports it). The SDK should ship it in a major release, or keep `getOrder` as a deprecated alias in the handwritten SDK. ### P2: Naming is inconsistent **Where:** - Paths. `/getCustomers` has a verb, `/customer/{customerId}` is singular, and `/shippingLabels` and `/getCustomers` are camelCase while every other path is lowercase. - Fields. Seven names are camelCase in a snake_case API, which are `Order.shippingAddress`, `Order.updatedDate`, `OrderItem.unitPrice`, the PATCH body's `shippingAddress`, and the `customerId` path and query parameters. - Enum. `OrderStatus` mixes `pending`, `Shipped` and `CANCELLED`. After: ``` GET /getCustomers -> GET /customers GET /customer/{customerId} -> GET /customers/{customer_id} GET /shippingLabels/{id} -> GET /shipping-labels/{label_id} shippingAddress -> shipping_address OrderStatus: pending | shipped | cancelled ``` Add the new paths and names, keep the old ones as deprecated aliases with `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594), and remove them in the next major version. ### P2: Timestamps use three formats **Where:** `created_at` is an RFC 3339 string, `Order.updatedDate` is a string with no format, and `Order.shipped` is Unix seconds. Use RFC 3339 UTC strings everywhere with `format: date-time`, and one suffix (`_at`). After the change, the fields are `updated_at` and `shipped_at`. ### P2: PATCH requires fields, and customers only have PUT **Where:** `PATCH /orders/{order_id}` requires `shippingAddress` and `notes`. `PUT /customer/{customerId}` has no PATCH alternative. A client that only wants to change the notes must resend the address. With PUT, a client built before a new customer field existed will wipe that field on every update. Make every PATCH field optional (JSON Merge Patch, RFC 7396) and add `PATCH /customers/{customer_id}`. The v2 draft already makes the PATCH fields optional, which is a safe change. ### P2: Status codes and error docs are incomplete - `POST /orders` and `POST /payments` return 200 for a create. Return 201 with a `Location` header in the next major version, because changing it now is breaking (the diff flags v2 for exactly this). - The 429 on `POST /orders` has no `Retry-After`, so clients guess how long to wait. Add `Retry-After`, and document 429 on every operation. - Eleven operations need auth but do not document 401. Four operations that address one resource do not document 404. ### P2: SDK ergonomics (`sample-sdk.d.ts`) `sdk_surface.py` reported the following: - `new BookshopClient(apiKey, baseUrl?, timeout?, retries?, debug?)` takes five positional arguments, while a `ClientOptions` interface already exists and is unused. Use `new BookshopClient({ apiKey, timeout })`, and read the key from an environment variable by default. - `orders.list(status?, expand: boolean)` puts a required parameter after an optional one and uses a boolean flag, so callers must write `list(undefined, true)`. - `orders.create(customerId: number, items, notes?, sendEmail?, coupon?)` takes five positional arguments with a boolean flag. Use `create({ customerId, items, sendEmail })`. - `orders.cancel(id, callback)` is the only callback method in a Promise-based SDK. - `customers: any`, `updateOrder(id, data: any): Promise<any>` and `WebhookHandler = (event: any)` turn off type checking where users need it most. - `ApiError extends Error` and `RateLimitError` have no common base, so `catch (e) { if (e instanceof ApiError) }` misses rate limits. Make `RateLimitError extends ApiError`, and add `code` and `requestId` to `ApiError`. - `ClientOptions.timeout` has no default. Ship a finite default (e.g. 60 seconds) and automatic retries on 429 and 503. - `orders.list()` returns `Promise<Order[]>`, which will hide pagination. Return an async iterator that fetches pages as needed. - Only 3 of 10 exported declarations have doc comments. ## Breaking-change risk list (v1.4.0 to proposed v2) `breaking_diff.py` found 24 breaking, 2 risky and 34 safe changes (full output in `out/diff-v1-v2.md`). The version moves from 1.4.0 to 1.5.0, which tells users nothing broke. Either ship v2 as `/v2` (2.0.0) with a migration guide and a sunset date for v1, or rework it so every change is additive. | Change in v2 | Who breaks | Additive alternative | |---|---|---| | `GET /getCustomers` removed | Every client listing customers | Keep it, mark it deprecated with Deprecation and Sunset headers, and point to `GET /customers` | | `GET /orders` returns an object instead of an array | Every client listing orders | Serve the envelope only on `/v2`, or behind a version header | | `Customer.id`, `customer_id` and `{customerId}` change from integer to string | Typed clients, and anyone who stored IDs as integers | Add string `customer_ref`, deprecate the integer | | `Order.total` removed (renamed `total_amount`, integer) | Anyone showing totals | Return both fields during the deprecation period | | `Error.message` removed, `ErrorResponse` replaced on 400 and 402 | Every error handler | Keep `message` (and `error.msg`) alongside the new fields | | `NewOrder.currency` newly required | Every `POST /orders` call | Make it optional, with a default of the account currency | | `POST /orders` and `POST /payments` now return 201 | Clients that check `== 200` | Only in a major version | | `Order.shippingAddress` becomes nullable | Clients that read it without a null check | Return an empty string, or only change it in v2 | | `PATCH` `shippingAddress` maxLength drops from 500 to 200 | Clients with longer addresses get 400 | Keep 500 | | Refund `amount` changes from number to integer, `reason` becomes an enum | Every refund call | Add `amount_minor` and accept free-text `reason` with a warning | | `GET /health` now requires auth | Load balancers and uptime checks | Keep it public | | `operationId` of DELETE renamed | Generated SDK users | Release with the SDK major version | | Webhook payload drops `event` | Every receiver | Send a new event version and keep both during migration | | `OrderStatus` gains `refunded` (risky) | Clients with exhaustive switches | Announce it, and document that clients must handle unknown values | | `customerId` query filter removed from `GET /orders` (risky) | Clients filtering by customer now get all orders, silently | Keep the filter, or reject it with a 400 so the change is visible | The second risky change is the most dangerous one in the list, because the request still succeeds. A client that filtered orders by customer now gets every customer's orders with no error. The diff also confirms that v2 makes several safe improvements, which are cursor pagination on `/customers` and `/orders`, an optional `Idempotency-Key` on `POST /orders`, `Retry-After` on 429, signed webhooks with `id`, `type` and `created_at`, problem details fields on errors, optional PATCH fields, and a deprecation flag on `DELETE /orders/{order_id}`. ## What's good - Auth uses a bearer token in the `Authorization` header, and `/health` is explicitly public with `security: []`. - `Order.id`, `Payment.id` and the order path parameters are already opaque strings. - `created_at` is an RFC 3339 `date-time` on both Customer and Order, which gives a clear standard to align the rest to. - `GET /orders/{order_id}/items` already uses a `{data, has_more}` envelope with a documented maximum page size of 100, so it is the model for the other lists. - `Order` carries `currency` next to `total`. - `quantity` has `minimum: 1`, and `notes` has a `maxLength`, so validation rules are in the spec where SDK generators can use them. - The SDK is Promise-based, exposes `readonly orders` as a resource namespace that mirrors the REST paths, and has a typed raw `request<T>()` escape hatch. - The v2 draft fixes many of the right things. Its problem is how it ships them. ## Not checked - Runtime behaviour, which includes real latency, actual rate limits, whether the server really ignores unknown fields, and default sort order of lists. - Documentation prose and examples, which `dx-audit` covers as part of onboarding. - Security beyond the API surface (authorization rules, tenant isolation). - The `./pagination` module re-exported by the SDK, which was not provided.skills/coding/api-design-review/examples/sample-sdk.d.ts1.9 KB3ec0b5d29d9fupstream ↗
// Deliberately flawed TypeScript SDK surface for testing sdk_surface.py. // It belongs to the fictional "Bookshop Orders" API in this folder. /** Options for creating a client. */ export interface ClientOptions { apiKey: string; baseUrl?: string; /** Milliseconds. There is no default, so requests can hang forever. */ timeout?: number; maxRetries?: number; } /** Entry point for the SDK. */ export declare class BookshopClient { constructor(apiKey: string, baseUrl?: string, timeout?: number, retries?: number, debug?: boolean); readonly orders: OrdersResource; customers: any; /** Raw request escape hatch. */ request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>; private signRequest(payload: string): string; } export declare class OrdersResource { /** List orders. Returns every order in one call. */ list(status?: string, expand: boolean): Promise<Order[]>; get(id: string): Promise<Order>; create(customerId: number, items: OrderItem[], notes?: string, sendEmail?: boolean, coupon?: string): Promise<Order>; cancel(id: string, callback: (err: Error | null, order?: Order) => void): void; updateOrder(id: string, data: any): Promise<any>; } export interface Order { id: string; customer_id: number; status: "pending" | "Shipped" | "CANCELLED"; total: number; createdAt: string; } export interface OrderItem { isbn: string; quantity: number; } export type WebhookHandler = (event: any) => void; export declare enum OrderStatus { Pending = "pending", Shipped = "Shipped", Cancelled = "CANCELLED" } /** Thrown for any non-2xx response. */ export declare class ApiError extends Error { status: number; message: string; } export declare class RateLimitError { retryAfter: number; } export declare function verifyWebhook(payload: string, header: string, secret: string, tolerance?: number): boolean; export * from "./pagination";skills/coding/api-design-review/reference.md28 KB22b9a7ff7bc2upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/dotslashsimran-simcraft-skills-coding-api-design-review.md