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

Install with Tessl CLI

npx tessl i github:sickn33/antigravity-awesome-skills --skill api-design-principles

What are skills?

1.04x

Quality

42%

Does it follow best practices?

Impact

88%

1.04x

Average score across 3 eval scenarios

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/api-design-principles/SKILL.md

SKILL.md

Review

Evals

Evaluation results

98%

11%

Inventory Management REST API Specification

REST resource design and HTTP semantics

Criteria

Without context

With context

Plural noun URLs

87%

No verb endpoints

100%

POST returns 201

100%

DELETE returns 204

100%

Partial update uses PATCH

100%

404 for missing resource

100%

422 for validation errors

100%

Pagination metadata

50%

100%

Pagination defaults

100%

Structured error format

87%

Nested resource URL

100%

Endpoint documentation

100%

GET list returns 200

100%

Without context: $0.3183 · 1m 10s · 15 turns · 62 in / 4,855 out tokens

With context: $0.8226 · 2m 15s · 28 turns · 1,780 in / 9,327 out tokens

70%

-2%

Public Weather Data API

REST versioning, rate limiting, and caching

Criteria

Without context

With context

URL versioning

100%

Version in all routes

75%

87%

Rate limit limit header

100%

88%

Rate limit remaining header

100%

88%

Rate limit reset header

100%

87%

429 status code

100%

Retry-After header on 429

100%

Cache-Control header

ETag header

Versioning documented

100%

Rate limiting documented

100%

HATEOAS links

Without context: $0.6212 · 2m 23s · 24 turns · 72 in / 9,539 out tokens

With context: $0.9154 · 3m 5s · 32 turns · 361 in / 11,982 out tokens

97%

Recipe Sharing Platform GraphQL API

GraphQL schema design and N+1 prevention

Criteria

Without context

With context

Schema file exists

100%

Relay cursor pagination

100%

Connection totalCount

100%

Mutation input types

50%

70%

Mutation payload types

100%

DataLoader implementation

100%

DataLoader used in resolver

100%

camelCase field names

100%

PascalCase type names

100%

@deprecated directive

100%

Non-null types used

100%

DataLoader documented

100%

Without context: $0.7479 · 2m 47s · 25 turns · 26 in / 10,730 out tokens

With context: $1.1649 · 4m 3s · 34 turns · 363 in / 15,555 out tokens

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

Table of Contents

Inventory Management REST API Specification Public Weather Data API Recipe Sharing 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.