Software Design
API and Interface Design
by Arsalan Usmani·Posted Sep 15, 2026
Design consistent, well-documented REST and GraphQL APIs with versioning, contracts, and OWASP-aligned security built in.
Guides the design of consistent, well-documented APIs and interfaces across REST and GraphQL. Covers resource modeling, versioning strategy, pagination, error contracts, and OpenAPI specification drafting. Applies OWASP API security guidance so interfaces ship with sound auth, validation, and rate-limiting patterns. Produces review-ready specs and rationale your engineers can implement directly.
What it does
8 actions, each one checked against your rules and recorded before it runs.
analyze_requirements
Extract resources, operations, and consumers from the design brief.
model_resources
Define entities, relationships, and naming conventions for the interface.
draft_openapi_spec
Author or revise a valid OpenAPI specification for the API.
design_graphql_schema
Compose GraphQL types, queries, and mutations with clear contracts.
define_versioning
Set URI, header, or schema evolution strategy for safe change over time.
check_owasp_alignment
Audit the design for auth, validation, rate limiting, and data exposure gaps.
author_documentation
Write usage docs with request and response examples for each operation.
record_decisions
Log design decisions and rationale for reviewer traceability.
How it runs
Every run follows the same governed path, from request to recorded result.
- 1
Read the requirements, existing spec, and constraints from the request.
- 2
Classify the interface style, resource model, and consumers.
- 3
Draft or refine the OpenAPI or GraphQL contract.
- 4
Define versioning, pagination, and error conventions.
- 5
Check the design against OWASP API security guidance.
- 6
Write documentation and usage examples.
- 7
Emit the spec, review notes, and decision log.
Governance & audit
What gets captured and verified on every single run.
Data access scope
Only the spec, requirements, and constraints supplied in the request are read. No repository or production system access is required.
Secret redaction
Any credentials, tokens, or connection strings found in input examples are redacted before drafting and never echoed into outputs.
PII handling
Designs flag endpoints that expose personal data and recommend minimization, masking, and authorization fields per OWASP guidance.
Evidence logging
Every run emits structured log evidence per step, retained for 90 days for review and traceability.
No autonomous writes
Generated specs are drafts for engineer review. The skill does not commit, deploy, or publish artifacts.
Example in action
Designing a partner-facing billing API for a SaaS platform
- 1
Analyze requirements. Parse the brief to identify metered events, invoices, and partner consumers.
- 2
Draft the spec. Author an OpenAPI 3.1 document with resources, cursor pagination, and a standard error envelope.
- 3
Audit security. Check OAuth2 scopes, input validation, and PII exposure on invoice endpoints.
- 4
Document usage. Write example requests and responses for the core operations.
- 5
Record decisions. Log the REST choice, header versioning, and pagination rationale for reviewers.
Skill manifest
The exact instructions this skill ships with, shown in full. Nothing hidden.
---
id: api-interface-design
version: 0.1.0
display_name: API and Interface Design
pack: community
category: engineering
risk_tier: low
tags:
- api-design
- rest
- graphql
- interface-design
- openapi
- developer-tools
primary_domain: engineering
secondary_domains:
- it-cybersecurity
- data-analytics
capabilities:
- code-api-operations
- drafting-authoring
- reasoning-analysis
verticals:
- saas
- telco
- bfsi
skill_type: composite
mechanisms:
- cognitive
- drafter
standards:
- owasp-llm
input_schema:
type: object
required:
- requirements
properties:
requirements:
type: string
description: Plain-language description of the API or interface to design, including
consumers and key operations.
existing_spec:
type: string
description: Optional existing OpenAPI document, GraphQL schema, or endpoint
list to review or extend.
style:
type: string
description: Preferred interface style such as REST, GraphQL, or open, where
open lets the skill recommend one.
constraints:
type: string
description: Optional constraints such as versioning policy, auth model, pagination
limits, or data residency rules.
output_schema:
type: object
required:
- spec
- review_notes
- decision_log
properties:
spec:
type: string
description: The drafted or revised API contract, such as an OpenAPI document
or GraphQL schema.
review_notes:
type: array
description: Findings on consistency, versioning, and security, each with severity
and a concrete recommendation.
decision_log:
type: array
description: Key design decisions with rationale, covering style choice, versioning,
pagination, and error model.
documentation:
type: string
description: Concise usage documentation with example requests and responses
for the main operations.
planner:
mode: dynamic
prompt_section: How to think about this task
max_steps: 10
max_duration_sec: 180
max_cost_usd: 0.1
model_tier: fast
allowed_step_kinds:
- tool_call
- llm_call
- output
evidence:
required_types:
- log
capture_per_step: true
retention_days: 90
routing:
intent_examples:
- Design a REST API for our billing service with an OpenAPI spec.
- Review this GraphQL schema and suggest versioning and pagination improvements.
- Draft an interface contract for a partner-facing payments API.
- Check our API design against OWASP security best practices.
not_for:
- Implementing or deploying working API server code.
- Runtime API gateway configuration or traffic management.
verifier_rules:
- The output spec is syntactically valid for its declared style, OpenAPI or GraphQL.
- Every endpoint or operation defines authentication, error responses, and versioning.
- Review notes reference concrete lines or operations in the spec, not generic advice.
---
## Overview
Designs consistent, well-documented APIs and interfaces across REST and GraphQL. Produces review-ready contracts, security findings, and design rationale. Aligns every design with OWASP API security guidance.
## How to think about this task
Start from the consumers. Identify who calls the interface, what operations they need, and what data crosses the boundary. Let that drive resource modeling and the choice between REST and GraphQL rather than defaulting to habit.
Favor boring consistency. One naming convention, one pagination pattern, one error envelope, one versioning strategy. Deviations need a written reason in the decision log.
Treat security as a design input, not a review afterthought. Every operation needs explicit auth, input validation, and a position on data minimization. Flag PII-bearing fields and recommend masking or scoping.
Write for the implementer. The spec, examples, and notes should let an engineer build the interface without a follow-up meeting.
## Capabilities
- analyze_requirements: extract resources, operations, and consumers from the request
- model_resources: define entities, relationships, and naming conventions
- draft_openapi_spec: author or revise a valid OpenAPI document
- design_graphql_schema: compose types, queries, and mutations
- define_versioning: set URI, header, or schema evolution strategy
- check_owasp_alignment: audit auth, validation, rate limiting, and data exposure
- author_documentation: write usage docs with request and response examples
- record_decisions: log design choices with rationale
## Inputs
`requirements` is the plain-language description of the API or interface to design. Include the consumers, the core operations, and any data sensitivity. This is the only required field.
`existing_spec` is an optional OpenAPI document, GraphQL schema, or endpoint list. When present, the skill reviews and extends it instead of starting from scratch.
`style` states a preferred interface style such as REST or GraphQL. Use open to let the skill recommend a style and justify the choice in the decision log.
`constraints` captures optional rules the design must respect, such as versioning policy, auth model, pagination limits, or data residency requirements.
## Outputs
`spec` is the drafted or revised contract. It is a valid OpenAPI document or GraphQL schema that an engineer can implement directly.
`review_notes` lists findings on consistency, versioning, and security. Each note carries a severity and a concrete, actionable recommendation tied to the spec.
`decision_log` records the key design decisions with rationale, including style choice, versioning strategy, pagination pattern, and error model.
`documentation` is concise usage guidance with example requests and responses for the main operations.
## Tools
- connectors: none required; operates on supplied specs and requirements
- operators: schema validation, diff analysis, convention linting
- primitives: llm_call, structured spec drafting, OWASP checklist evaluation
## Guardrails
- Only the spec, requirements, and constraints supplied in the request are read. No repository or production system access is required.
- Any credentials, tokens, or connection strings found in input examples are redacted before drafting and never echoed into outputs.
- Designs flag endpoints that expose personal data and recommend minimization, masking, and authorization fields per OWASP guidance.
- Every run emits structured log evidence per step, retained for 90 days for review and traceability.
- Generated specs are drafts for engineer review. The skill does not commit, deploy, or publish artifacts.
## Examples
A SaaS team needs a partner-facing usage-billing API. The request supplies requirements describing metered events, monthly invoices, and partner consumers, with style set to REST and a constraint requiring header-based versioning.
The skill models UsageEvent and Invoice resources, drafts an OpenAPI 3.1 spec with cursor pagination, a RFC 7807 problem-details error envelope, and OAuth2 client-credentials auth. It flags that the invoice endpoint exposes customer email addresses and recommends scoping the response to invoice IDs and amounts.
Outputs include the spec, three review notes, a decision log covering the REST choice and header versioning, and documentation with example POST /v1/events and GET /v1/invoices calls.Reviews
Reviews from teams using API and Interface Design.
No reviews yet
Be the first to share how API and Interface Design works for your team.
Discussion(0)
No comments yet. Be the first.