api-design-assistant

Design and review APIs with suggestions for endpoints, parameters, return types, and best practices. Use when designing new APIs from requirements, reviewing existing API designs, generating API documentation, or getting implementation guidance. Supports REST APIs with focus on endpoint structure, request/response schemas, authentication, pagination, filtering, versioning, and OpenAPI specifications. Triggers when users ask to design, review, document, or improve APIs.

1.08x

Quality

92%

Does it follow best practices?

Impact

98%

1.08x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Evaluation results

100%

API Review: Customer Support Ticketing System

RESTful API review and correction

Criteria

Without context

With context

No verbs in URLs

100%

Plural resource names

100%

Path param for resource ID

100%

Correct HTTP methods

100%

PATCH for partial update

100%

POST for actions

100%

201 for creation

100%

204 for deletion

100%

Standard error structure

100%

Correct error status codes

100%

Nested resource for comments

100%

98%

Product Catalog API: OpenAPI Specification

OpenAPI spec generation with collections and schemas

Criteria

Without context

With context

OpenAPI 3.0 header

100%

Required top-level keys

100%

Plural lowercase resource paths

100%

Reusable $ref schemas

100%

Reusable $ref responses or parameters

100%

Collection response shape

90%

100%

Pagination fields

75%

Cursor-based pagination

100%

ISO 8601 datetime format

100%

Error response structure

100%

Nested category-products path

100%

Sort query parameter

75%

100%

97%

13%

Payment Processing API: Hardening for Production

Authentication, versioning, and rate limiting design

Criteria

Without context

With context

JWT for mobile

50%

62%

API keys for server-to-server

100%

OAuth2 for third-party

100%

URL versioning

100%

Removing field requires version

100%

Type change requires version

100%

Adding optional fields no version

100%

Rate limit headers named correctly

100%

Idempotency key for order creation

100%

429 for rate limit exceeded

100%

Repository: ArabelaTso/Skills-4-SE
Commit: 0f00a4f

Evaluated: 29 days ago
Agent: Claude Code
Model: Claude Sonnet 4.6

Table of Contents

API Review: Customer Support Ticketing System Product Catalog API: OpenAPI Specification Payment Processing API: Hardening for Production

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.