api-design

Design RESTful and GraphQL APIs following best practices. Use when creating new APIs, refactoring existing endpoints, or documenting API specifications. Handles OpenAPI, REST, GraphQL, versioning.

Invalid

This skill can't be scored yet

Validation errors are blocking scoring. Review and fix them to unlock Quality, Impact and Security scores. See what needs fixing →

Evaluation results

89%

10%

Hotel Room Booking API Design

REST resource naming, HTTP methods, and response codes

Criteria

Without context

With context

Plural resource names

100%

Noun-based paths

50%

100%

Logical resource nesting

100%

URL versioning

87%

100%

Correct HTTP method usage

100%

201 for creation

100%

204 for deletion

100%

62%

404 and 400 codes

100%

Location header on 201

Timestamps in response

100%

Structured error format

100%

Error details field

100%

93%

15%

News Article API — OpenAPI Specification

Pagination response format and OpenAPI 3.0 documentation

Criteria

Without context

With context

OpenAPI 3.0 version

100%

Required top-level sections

100%

Pagination query params

75%

100%

Pagination metadata in response

70%

100%

Pagination links in response

100%

JWT bearer auth defined

100%

Auth applied to write endpoints

100%

Reusable $ref schemas

100%

Timestamps in schema

100%

Sorting query parameter

100%

Filter query parameters

100%

Field selection support

100%

15%

Inventory Management API Design

Batch operations, field selection, filtering, and sorting patterns

Criteria

Without context

With context

Batch endpoint path

100%

Batch operations array

100%

Batch supports multiple actions

100%

Field selection via fields param

100%

Sort with hyphen-prefix for descending

50%

100%

Filter query parameters

100%

Pagination in list response

75%

100%

Pagination links

100%

ETag or Cache-Control headers

100%

URL versioning present

100%

Plural resource name

100%

Repository: supercent-io/skills-template
Commit: c033769

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

Table of Contents

Hotel Room Booking API Design News Article API — OpenAPI Specification Inventory Management API Design

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.