timbenniks/sdk-readiness-audit

SDK readiness audit

Audit whether an API is actually SDK friendly and actionable. Do not generate an SDK. Diagnose gaps and provide concrete fixes.

Scope

• Accept OpenAPI (URL or local file), GraphQL schema (SDL or introspection), or REST docs (links or markdown)
• Produce a readiness scorecard, prioritized refactors, SDK pain points, and spec fix suggestions
• Avoid guessing; mark unknowns and request missing inputs

Mandatory intake questions (ask in one concise block)

1. Source of truth
   • OpenAPI URL or local path, GraphQL SDL/introspection, or REST docs link/markdown
2. Target SDK consumers
   • Primary languages or platforms (if any)
   • Primary use cases or top workflows
3. Auth and environments
   • Auth methods, token types, and environments (prod/sandbox)
4. Known pain points
   • Any current client friction or support issues

If the user already provided answers, restate and confirm.

Workflow

1. Load inputs
   • For OpenAPI, parse: servers, security, tags, paths, components, schemas
   • For GraphQL, parse: types, inputs, enums, connections, directives, deprecations
   • For REST docs, build an endpoint inventory table before scoring
2. Build a surface inventory
   • Endpoints/operations and their purpose
   • Request and response shapes
   • Auth, pagination, errors, versioning, rate limits
3. Evaluate with the rubric
   • Score each category 0 to 5
   • Cite concrete evidence (endpoint names, schema fields, headers)
4. Produce outputs
   • Scorecard
   • Refactors with priority
   • "If we shipped an SDK today" pain points
   • Suggested OpenAPI fixes and x-* extensions
5. Write the audit file
   • Save the full output to sdk-readiness-audit.md
6. Call out unknowns
   • List missing or ambiguous areas that block full confidence

Scoring rubric (0 to 5)

Score each category. Use "unknown" if evidence is missing.

0 = missing or harmful 1 = inconsistent or ad hoc 3 = workable but rough for SDKs 5 = strong and SDK friendly

Categories (weighted):

• Auth and environments (weight 2)
• Errors and error model (weight 2)
• Pagination and collection design (weight 2)
• Naming and resource model
• Consistency and conventions
• Data model quality (types, required/optional, enums, nullability)
• Filtering, sorting, and search
• Versioning and stability
• Idempotency and safety semantics
• Long running operations and async jobs
• Rate limits and retries
• Documentation and examples
• SDK metadata readiness (operationId, tags, schema names)

Overall score (0 to 100):

• Weighted average * 20
• If any critical category (auth, errors, pagination) is <= 2, cap overall at 59 and label "not ready"

Output format (required)

Write the full output to sdk-readiness-audit.md. In chat, provide a brief summary and point to the file.

1. Readiness verdict

   • Ready / Borderline / Not ready
   • Overall score

2. SDK readiness scorecard

   • Table with category, score, evidence, and brief notes

3. Concrete refactors needed

   • Prioritized list with P0/P1/P2
   • Each item includes: current issue, why it hurts SDKs, proposed fix

4. If we shipped an SDK today, here is what would hurt

   • Short bullet list focused on developer friction

5. Suggested OpenAPI fixes and x-* extensions

   • Provide specific fixes and optional vendor extensions
   • Use small YAML snippets when helpful

6. Unknowns and requested follow ups

   • Only if needed

OpenAPI fixes and x-* extensions (guidance)

Suggest fixes that improve client generation and developer experience. Examples:

• Normalize operationId or provide x-sdk-method-name
• Group operations with tags or x-sdk-group
• Define consistent error schema (Problem Details or equivalent)
• Standardize pagination and document in x-pagination
• Mark idempotent operations with x-idempotency
• Mark retryable errors with x-retryable
• Add examples and x-examples per operation
• Clarify rate limit headers with x-rate-limit

Keep extensions minimal and consistent. Do not invent semantics that conflict with the spec.

GraphQL specific checks

• Prefer consistent connection-based pagination for lists
• Avoid unbounded lists without pagination args
• Use input objects for mutations
• Prefer enums over freeform strings
• Provide clear deprecations
• Document nullability and error behavior

REST docs specific checks

• Build an explicit endpoint inventory first
• Identify missing details (auth, error schema, pagination, versioning)
• Propose a minimal OpenAPI skeleton to close gaps

Acceptance criteria

Output is correct only if:

• All intake questions were asked or confirmed
• Evidence is cited for each score
• Refactors are concrete and actionable
• Pain points are clearly stated
• OpenAPI fixes or x-* extensions are suggested where relevant
• Unknowns are explicitly listed when information is missing
• sdk-readiness-audit.md was written with the full audit