api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

1.03x

Quality

70%

Does it follow best practices?

Impact

91%

1.03x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/data/02-architect-apidesign/SKILL.md

Evaluation results

91%

Book Store API Design

REST resource-oriented design and pagination

Criteria

Without context

With context

Plural collection names

100%

No action-based endpoints

100%

Correct HTTP method usage

100%

Nested resource endpoints

100%

Pagination query parameters

100%

Paginated response shape

100%

HATEOAS _links

75%

100%

Consistent error response structure

70%

100%

Correct status codes

100%

API versioning present

Filtering support

100%

Without context: $0.5567 · 2m 26s · 24 turns · 31 in / 9,985 out tokens

With context: $0.6863 · 2m 22s · 26 turns · 31 in / 9,593 out tokens

83%

Community Q&A Platform GraphQL API

GraphQL schema design with Relay pagination and DataLoaders

Criteria

Without context

With context

Relay cursor pagination

100%

PageInfo fields

100%

totalCount on Connection

100%

Mutation Input types

100%

Mutation Payload types

100%

Structured mutation errors

100%

DataLoader for N+1

83%

100%

Enums for status fields

Custom scalars

100%

@deprecated directive

Schema defined before resolvers

100%

Without context: $0.4698 · 2m 18s · 16 turns · 19 in / 9,741 out tokens

With context: $0.7090 · 2m 35s · 23 turns · 140 in / 11,765 out tokens

100%

Legacy Inventory API Modernization

REST error handling, HATEOAS, and API versioning

Criteria

Without context

With context

No POST-for-everything

100%

Plural collection endpoint

100%

Correct error status codes

100%

Structured error response

100%

HATEOAS _links in responses

80%

100%

API versioning in paths

100%

OpenAPI spec produced

100%

Rate limiting mentioned

100%

Not tight-coupled to DB schema

100%

Versioning migration path documented

100%

Without context: $0.3752 · 2m 5s · 14 turns · 21 in / 7,692 out tokens

With context: $0.8436 · 3m 20s · 31 turns · 35 in / 13,312 out tokens

Repository: majiayu000/claude-skill-registry
Commit: 6213d1a

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

Table of Contents

Book Store API Design Community Q&A Platform GraphQL API Legacy Inventory API Modernization

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.