⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

api-design-review

dotslashsimran@dotslashsimran⭐ 378 stars· last commit 6d ago· 0 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 378 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

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.

MIT License Skills Claude Code Stars

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.sh for 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

SkillWhat it does
perspective-illusionIllustrated 3D loops in the Japanese perspective-illusion style: flat scenes that open into depth.
code-loopAny three.js scene or shader rendered as a seamless loop, checked for seams, freezes and blinks.
reverse-engineer-videoHand it a viral clip, get a remake plan: every cut, camera move and beat.
scripted-screencastProduct demos written as a script and rendered frame-perfect. No retakes.
repo-timelapseYour git history as a video of the project growing.
rough-cutRaw talking footage to a tight first cut: pauses, ums and retakes removed.
clean-audioVoice cleanup that measures first, then keeps every word clear.
vox-explainerVox-style explainer graphics timed word by word to a voiceover.

🧑‍💻 Engineering

SkillWhat it does
codebase-mapLearn an unfamiliar repo fast by tracing one real request end to end.
bisect-anythingFind the exact commit behind any regression, then the exact lines.
flaky-test-killerFix why a test is flaky, never with retries, and prove the fix.
benchmark-honestlyBenchmarks that survive scrutiny, with confidence intervals.
api-design-reviewReview an API, SDK or CLI, and catch breaking changes.
security-threat-modelThreat-model your own app from its real code, LLM apps included.
dx-auditTry a developer tool like a brand-new user and time it to first success.

🧠 Learning

SkillWhat it does
paper-to-runnableA research paper turned into the smallest honest implementation of its idea.
system-design-from-scratchBuild a tiny real system, load-test it, break it, write up the trade-offs.
from-scratchLearn anything by building the smallest version of it, one step at a time.
teach-backYou explain it, Claude finds the gaps, you get a one-page cheat sheet.

🎨 Design

SkillWhat it does
image-genImages with your own Gemini or OpenAI key, consistent across a set.
brand-kitLearn a brand from its live site into a kit the other skills apply.

🧭 Planning

SkillWhat it does
skill-routerPicks the right skill for a task, or a chain of two or three.
next-stepA big messy goal turned into one clear next action at a time.
video-scriptShort 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 withThen
A viral clipreverse-engineer-video → code-loop or perspective-illusion
A research paperpaper-to-runnable → vox-explainer
A new SDKdx-audit → scripted-screencast
"It got slower"benchmark-honestly → bisect-anything
A new jobcodebase-map → flaky-test-killer
Raw footagerough-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, None
    
  • skills/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

// REPO STATS

378 stars
0 open issues
Last commit: 6d ago