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.13x

Quality

44%

Does it follow best practices?

Impact

94%

1.13x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/backend-development/skills/api-design-principles/SKILL.md

Evaluation results

95%

-2%

Inventory Management REST API Design

REST resource naming and HTTP semantics

Criteria

Without context

With context

Plural nouns for collections

100%

No verb-based endpoints

100%

GET for retrieval

100%

POST for creation

100%

PUT or PATCH for updates

100%

DELETE for removal

100%

201 Created for POST

100%

204 No Content for DELETE

100%

404 for missing resources

100%

422 for validation errors

100%

Shallow nesting

57%

28%

409 for conflict

100%

91%

21%

Customer Transactions API

Pagination, filtering, and error response structure

Criteria

Without context

With context

Paginated response shape

25%

100%

Default page size 20

100%

Max page size 100

100%

Default page 1

100%

Error response has error field

25%

100%

Error response has message field

100%

Error response has details field

100%

75%

Rate limit headers present

100%

429 with Retry-After

100%

Status-based filtering

100%

FastAPI + Pydantic

100%

Sorting supported

97%

12%

Blog Platform GraphQL API

GraphQL schema design and resolver patterns

Criteria

Without context

With context

Schema file first

100%

Relay connection types

100%

PageInfo fields

100%

Cursor-based pagination args

100%

DataLoader for relationships

100%

Mutation input types

37%

62%

Mutation payload with errors

100%

@deprecated used

100%

Status enum defined

100%

PascalCase types

100%

camelCase fields

100%

ariadne resolvers

100%

Repository: Dicklesworthstone/pi_agent_rust
Commit: 47823e3

Evaluated: about 1 month ago
Agent: Claude Code
Model: Claude Sonnet 4.6

Table of Contents

Inventory Management REST API Design Customer Transactions API Blog Platform GraphQL API

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.