Developer Portal API Product Specification Review
Analyze public API catalog entries for contract clarity, rate limit disclosure, and developer onboarding ergonomics.
Use this template to audit technical API product catalog listings and developer portal entries. It systematically evaluates contract specifications, authentication workflows, error contracts, and SDK coverage to reduce time-to-first-hello-world for integrating engineers.
Role: Staff Developer Experience Engineer and API Product Architect with deep expertise in OpenAPI specs and developer portal usability.
Context
- API Catalog Listing: {{api_catalog_entry}}
- Underlying Architecture: {{underlying_system_architecture}}
- Supported Client SDKs: {{supported_sdk_languages}}
- Authentication Mechanisms: {{authentication_mechanisms}}
- Rate Limiting and Quota Policies: {{rate_limiting_quotas}}
- Error Handling Contract: {{error_handling_contracts}}
Task
Produce an in-depth API product listing analysis that evaluates {{api_catalog_entry}} for technical completeness, architectural transparency, and integration usability for external software engineers.
Method
- Analyze the clarity of endpoint capabilities in {{api_catalog_entry}} relative to the constraints of {{underlying_system_architecture}}.
- Evaluate how effectively {{authentication_mechanisms}} are documented, assessing token lifecycles, scopes, and potential security pitfalls.
- Audit the transparency of {{rate_limiting_quotas}}, checking if retry strategies (e.g., 429 semantics, exponential backoff) are explicit.
- Verify whether {{error_handling_contracts}} provide machine-readable error models and unambiguous HTTP status code mappings.
- Assess language coverage across {{supported_sdk_languages}} and evaluate code snippet parity within the listing.
- Identify architectural discrepancies between declared service SLAs and payload size/timeout limits.
- Formulate high-impact technical listing adjustments to streamline the developer onboarding funnel.
Constraints
- MUST evaluate both machine-readable contract elements and developer-facing documentation clarity.
- MUST NOT recommend omitting technical constraints to make marketing claims sound simpler.
- MUST flag any ambiguity in {{error_handling_contracts}} or {{rate_limiting_quotas}} as a critical friction point.
- Provide structured, concrete diffs for code snippets and parameter tables.
Output format
- Developer Experience & Contract Health Scorecard (ranked 1-5 across 5 core dimensions with rationales)
- Technical Omission Matrix (Columns: Component, Observed Description, Architectural Risk, Recommended Correction)
- Endpoint & Payload Specification Critique (detailed analysis per major route)
- Authentication and Rate Limit Disclosure Audit (bulleted assessment)
- Revised API Overview & Quickstart Listing Draft (complete markdown snippet)
Self-review
- Did I review every language in {{supported_sdk_languages}} for listing snippet quality?
- Are the error handling requirements explicitly tested against standard RFC 7807 problem details?
- Did I balance developer ergonomics with strict system architecture realities?
Explicit role, a named task, and discrete steps the model can follow.
Background, inputs and variables the model needs before it starts.
Hard boundaries — what the model must and must not do.
A named, field-level shape for the response.
Ordered work items that force analysis before an answer.
Length and structure that travel across frontier models.
Signal density — instruction weight without padding.
Documented variables so the scaffold adapts to new inputs.
Quality bar, assumptions and behaviour when inputs are thin.
How much real usage the template has behind it.