api-design

Name: api-design
Author: krzysztofsurdy

44installs1forks

How to install api-design?

krzysztofsurdy/code-virtuoso/api-design

$npx -y skills add krzysztofsurdy/code-virtuoso --skill api-design

Installs into the current project.

Summary

REST and GraphQL API design principles for consistent, predictable, and evolvable APIs. Use when the user asks to design a new API, review an existing API, choose between REST and GraphQL, plan API versioning, define error response contracts, implement pagination, or establish AP

Files · 1

View on GitHub

SKILL.md

1	# API Design
2
3	Principles and patterns for designing APIs that are consistent, predictable, and easy to evolve. Applies to any language or framework — the focus is on protocol-level design decisions, not implementation details.
4
5	A well-designed API treats its surface as a product: consumers should be able to predict behavior, recover from errors, and integrate without reading source code.
6
7	## When to Use
8
9	- Designing a new public or internal API from scratch
10	- Reviewing an existing API for consistency and usability
11	- Choosing between REST and GraphQL for a project
12	- Planning API versioning or migration strategy
13	- Defining error response contracts across services
14	- Establishing API standards for a team or organization
15
16	## REST vs GraphQL
17
18	\| Aspect \| REST \| GraphQL \|
19	\|---\|---\|---\|
20	\| Best for \| CRUD-heavy, resource-oriented domains \| Complex, interconnected data with varied client needs \|
21	\| Data fetching \| Fixed response shapes per endpoint \| Client specifies exact fields needed \|
22	\| Over-fetching \| Common — endpoints return full resources \| Eliminated — clients request only what they need \|
23	\| Under-fetching \| Common — requires multiple round trips \| Eliminated — single query can span relations \|
24	\| Caching \| Built-in HTTP caching (ETags, Cache-Control) \| Requires custom caching (normalized stores, persisted queries) \|
25	\| File uploads \| Native multipart support \| Requires workarounds (multipart spec or separate endpoint) \|
26	\| Real-time \| Webhooks, SSE, or polling \| Subscriptions built into the spec \|
27	\| Tooling maturity \| Mature — OpenAPI, Postman, HTTP clients \| Growing — Apollo, Relay, GraphiQL \|
28	\| Learning curve \| Lower — leverages existing HTTP knowledge \| Higher — schema language, resolvers, query optimization \|
29	\| Error handling \| HTTP status codes + response body \| Always 200 — errors in response `errors` array \|
30	\| Versioning \| URL path, headers, or query params \| Schema evolution via deprecation + additive changes \|
31
32	Choose REST when: your domain maps naturally to resources and CRUD operations, you need HTTP caching, or your clients are simple (mobile apps, third-party integrations).
33
34	Choose GraphQL when: clients have highly varied data needs, you are aggregating multiple backend services, or you want a strongly typed contract between frontend and backend.
35
36	Both are valid. Many systems use REST for external/public APIs and GraphQL for internal frontend-backend communication.
37
38	## REST Design Principles
39
40	REST APIs model the domain as resources and use HTTP semantics to operate on them.
41
42	Core rules:
43	- Resources are nouns, not verbs: `/orders`, not `/getOrders`
44	- HTTP methods are the verbs: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes
45	- URLs identify resources; query parameters filter, sort, or paginate them
46	- Use plural nouns for collections: `/users`, `/users/{id}`
47	- Limit nesting to two levels: `/users/{id}/orders` is fine; `/users/{id}/orders/{id}/items/{id}/variants` is not
48	- Use HTTP status codes meaningfully — do not return 200 for everything
49	- Support content negotiation via `Accept` and `Content-Type` headers
50
51	HATEOAS (Hypermedia as the Engine of Application State) adds discoverability by including links in responses. Useful for public APIs but often overkill for internal services:
52
53	```json
54	{
55	"id": 42,
56	"status": "shipped",
57	"_links": {
58	"self": { "href": "/orders/42" },
59	"cancel": { "href": "/orders/42/cancel", "method": "POST" },
60	"customer": { "href": "/customers/7" }
61	}
62	}
63	```
64
65	See [REST Patterns Reference](references/rest-patterns.md) for detailed conventions.
66
67	## GraphQL Design Principles
68
69	GraphQL APIs expose a strongly typed schema that clients query declaratively.
70
71	Core rules:
72	- Design schema-first — define the type system before writing resolvers
73	- Types represent domain concepts; fields represent attributes and relations
74	- Queries read data, mutations write data, subscriptions stream data
75	- Use the type system to enforce constraints (non-null, enums, input types)
76	- Avoid deeply nested schemas that create unpredictable query costs
77	- Solve N+1 problems with batching (dataloader pattern)
78	- Limit query depth and complexity to prevent abuse
79
80	Schema-first example:
81
82	```graphql
83	type User {
84	id: ID!
85	name: String!
86	email: String!
87	orders(first: Int, after: String): OrderConnection!
88	}
89
90	type Order {
91	id: ID!
92	total: Float!
93	status: OrderStatus!
94	creat

People who liked this also viewed

6 picks

Type

api-design

44installs1forks

View on GitHub

How to install api-design?

krzysztofsurdy/code-virtuoso/api-design

$npx -y skills add krzysztofsurdy/code-virtuoso --skill api-design

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Design
2
3	Principles and patterns for designing APIs that are consistent, predictable, and easy to evolve. Applies to any language or framework — the focus is on protocol-level design decisions, not implementation details.
4
5	A well-designed API treats its surface as a product: consumers should be able to predict behavior, recover from errors, and integrate without reading source code.
6
7	## When to Use
8
9	- Designing a new public or internal API from scratch
10	- Reviewing an existing API for consistency and usability
11	- Choosing between REST and GraphQL for a project
12	- Planning API versioning or migration strategy
13	- Defining error response contracts across services
14	- Establishing API standards for a team or organization
15
16	## REST vs GraphQL
17
18	\| Aspect \| REST \| GraphQL \|
19	\|---\|---\|---\|
20	\| Best for \| CRUD-heavy, resource-oriented domains \| Complex, interconnected data with varied client needs \|
21	\| Data fetching \| Fixed response shapes per endpoint \| Client specifies exact fields needed \|
22	\| Over-fetching \| Common — endpoints return full resources \| Eliminated — clients request only what they need \|
23	\| Under-fetching \| Common — requires multiple round trips \| Eliminated — single query can span relations \|
24	\| Caching \| Built-in HTTP caching (ETags, Cache-Control) \| Requires custom caching (normalized stores, persisted queries) \|
25	\| File uploads \| Native multipart support \| Requires workarounds (multipart spec or separate endpoint) \|
26	\| Real-time \| Webhooks, SSE, or polling \| Subscriptions built into the spec \|
27	\| Tooling maturity \| Mature — OpenAPI, Postman, HTTP clients \| Growing — Apollo, Relay, GraphiQL \|
28	\| Learning curve \| Lower — leverages existing HTTP knowledge \| Higher — schema language, resolvers, query optimization \|
29	\| Error handling \| HTTP status codes + response body \| Always 200 — errors in response `errors` array \|
30	\| Versioning \| URL path, headers, or query params \| Schema evolution via deprecation + additive changes \|
31
32	Choose REST when: your domain maps naturally to resources and CRUD operations, you need HTTP caching, or your clients are simple (mobile apps, third-party integrations).
33
34	Choose GraphQL when: clients have highly varied data needs, you are aggregating multiple backend services, or you want a strongly typed contract between frontend and backend.
35
36	Both are valid. Many systems use REST for external/public APIs and GraphQL for internal frontend-backend communication.
37
38	## REST Design Principles
39
40	REST APIs model the domain as resources and use HTTP semantics to operate on them.
41
42	Core rules:
43	- Resources are nouns, not verbs: `/orders`, not `/getOrders`
44	- HTTP methods are the verbs: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes
45	- URLs identify resources; query parameters filter, sort, or paginate them
46	- Use plural nouns for collections: `/users`, `/users/{id}`
47	- Limit nesting to two levels: `/users/{id}/orders` is fine; `/users/{id}/orders/{id}/items/{id}/variants` is not
48	- Use HTTP status codes meaningfully — do not return 200 for everything
49	- Support content negotiation via `Accept` and `Content-Type` headers
50
51	HATEOAS (Hypermedia as the Engine of Application State) adds discoverability by including links in responses. Useful for public APIs but often overkill for internal services:
52
53	```json
54	{
55	"id": 42,
56	"status": "shipped",
57	"_links": {
58	"self": { "href": "/orders/42" },
59	"cancel": { "href": "/orders/42/cancel", "method": "POST" },
60	"customer": { "href": "/customers/7" }
61	}
62	}
63	```
64
65	See [REST Patterns Reference](references/rest-patterns.md) for detailed conventions.
66
67	## GraphQL Design Principles
68
69	GraphQL APIs expose a strongly typed schema that clients query declaratively.
70
71	Core rules:
72	- Design schema-first — define the type system before writing resolvers
73	- Types represent domain concepts; fields represent attributes and relations
74	- Queries read data, mutations write data, subscriptions stream data
75	- Use the type system to enforce constraints (non-null, enums, input types)
76	- Avoid deeply nested schemas that create unpredictable query costs
77	- Solve N+1 problems with batching (dataloader pattern)
78	- Limit query depth and complexity to prevent abuse
79
80	Schema-first example:
81
82	```graphql
83	type User {
84	id: ID!
85	name: String!
86	email: String!
87	orders(first: Int, after: String): OrderConnection!
88	}
89
90	type Order {
91	id: ID!
92	total: Float!
93	status: OrderStatus!
94	creat

People who liked this also viewed

6 picks

Type