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

41%

Does it follow best practices?

Impact

93%

1.13x

Average score across 6 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Evaluation results

96%

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

42%

409 for conflict

100%

90%

13%

Customer Transactions API

Pagination, filtering, and error response structure

Criteria

Without context

With context

Paginated response shape

58%

100%

Default page size 20

100%

Max page size 100

100%

Default page 1

100%

Error response has error field

100%

Error response has message field

100%

Error response has details field

25%

62%

Rate limit headers present

100%

429 with Retry-After

50%

100%

Status-based filtering

100%

FastAPI + Pydantic

100%

Sorting supported

97%

19%

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

50%

62%

Mutation payload with errors

100%

@deprecated used

100%

Status enum defined

100%

PascalCase types

100%

camelCase fields

100%

ariadne resolvers

100%

83%

-7%

Library Catalogue REST API — Multi-Version Support

HATEOAS links and API versioning

Criteria

Without context

With context

URL versioning used

83%

100%

Both versions present

100%

_links field in responses

100%

58%

self link present

100%

60%

Payment Processing API — Production Readiness

OpenAPI documentation, health checks, caching, and idempotency

Criteria

Without context

With context

FastAPI title and description

100%

FastAPI version set

100%

docs_url and redoc_url configured

100%

Endpoint tags used

100%

Endpoint summary or docstring

100%

/health endpoint present

50%

100%

/health/detailed endpoint present

100%

Idempotency-Key header accepted

100%

Idempotency deduplication logic

100%

ETag header on GET

100%

Cache-Control header on GET

100%

If-None-Match / 304 handling

100%

94%

Content Feed GraphQL API — Multi-Type Search and Live Updates

GraphQL advanced schema: subscriptions, unions, interfaces, custom scalars

Criteria

Without context

With context

schema.graphql present

100%

Union type for search

100%

Interface for shared fields

100%

Types implement interface

100%

DateTime custom scalar

100%

URL or domain scalar

100%

Subscription type defined

100%

ariadne SubscriptionType used

100%

ariadne resolver bindings

100%

PascalCase type names

100%

camelCase field names

100%

Schema notes explain union/interface choice

100%

Enums for content status

100%

Repository: wshobson/agents
Commit: 70444e5

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

Table of Contents

Inventory Management REST API Design Customer Transactions API Blog Platform GraphQL API Library Catalogue REST API — Multi-Version Support Payment Processing API — Production Readiness Content Feed GraphQL API — Multi-Type Search and Live Updates

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.