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.

Install with Tessl CLI

npx tessl i github:wshobson/agents --skill api-design-principles

What are skills?

Overall
score

65%

Review — 58%

Does it follow best practices?

If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:

npx tessl skill review --optimize ./path/to/skill

Learn more

Evaluation — 94%

Agent success when using this skill

Validation — 10 / 11 Passed

Validation for skill structure

SKILL.md

Review

Evals

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%

Without context: $0.5331 · 1m 44s · 23 turns · 23 in / 7,214 out tokens

With context: $0.9799 · 2m 49s · 39 turns · 323 in / 11,746 out tokens

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

Without context: $0.5465 · 2m 14s · 19 turns · 18 in / 9,374 out tokens

With context: $0.9780 · 2m 49s · 30 turns · 29 in / 10,310 out tokens

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%

Without context: $0.4483 · 1m 59s · 16 turns · 65 in / 7,744 out tokens

With context: $0.7837 · 2m 30s · 24 turns · 71 in / 9,018 out tokens

Evaluated: 1 day ago
Agent: Claude Code

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.