What is the difference between REST, GraphQL, and gRPC?

REST uses resource-based URIs and HTTP semantics; GraphQL exposes a typed schema with flexible queries; gRPC uses Protocol Buffers and RPC-style services with potential streaming.

When should I prefer GraphQL over REST?

Choose GraphQL when clients need flexible, precise querying across multiple resources, strong typing, and efficient data fetching; it’s especially useful for mobile/web clients with varying data needs.

How do you ensure backward compatibility in API design?

Plan with versioning, deprecation policies, and clear migration paths; avoid breaking changes in published endpoints, and provide non-breaking updates with proper documentation and SDKs.

api-design

Scanned

skill

npx machina-cli add skill Fujigo-Software/f5-framework-claude/api-design --openclaw

Files (1)

SKILL.md

11.6 KB

API Design Skills

Overview

API design knowledge for building clean, consistent, and developer-friendly APIs. This domain covers REST, GraphQL, gRPC, documentation standards, and best practices.

API Types Comparison

┌─────────────────────────────────────────────────────────────────────────────┐
│                        API Types Comparison                                  │
├──────────────┬──────────────┬──────────────┬──────────────┬─────────────────┤
│ Aspect       │ REST         │ GraphQL      │ gRPC         │ Best For        │
├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤
│ Protocol     │ HTTP/1.1     │ HTTP/1.1     │ HTTP/2       │                 │
│ Format       │ JSON/XML     │ JSON         │ Protobuf     │                 │
│ Schema       │ Optional     │ Required     │ Required     │                 │
│              │ (OpenAPI)    │ (SDL)        │ (.proto)     │                 │
│ Caching      │ HTTP native  │ Complex      │ Manual       │                 │
│ Real-time    │ Polling/SSE  │ Subscriptions│ Streaming    │                 │
│ Learning     │ Easy         │ Medium       │ Hard         │                 │
├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤
│ Use Cases    │ Public APIs  │ Flexible     │ Microservices│                 │
│              │ CRUD apps    │ Mobile apps  │ Low latency  │                 │
│              │ Web services │ Aggregation  │ High perf    │                 │
└──────────────┴──────────────┴──────────────┴──────────────┴─────────────────┘

REST Maturity Model (Richardson)

┌─────────────────────────────────────────────────────────────────┐
│                   REST Maturity Model                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Level 3: Hypermedia Controls (HATEOAS)                         │
│           ├── Self-documenting APIs                              │
│           ├── Discoverability via links                          │
│           └── Decoupled client-server evolution                  │
│                        ↑                                         │
│  Level 2: HTTP Verbs + Status Codes                             │
│           ├── GET, POST, PUT, PATCH, DELETE                     │
│           ├── Proper status codes (200, 201, 404, etc.)         │
│           └── Safe and idempotent methods                        │
│                        ↑                                         │
│  Level 1: Resources                                              │
│           ├── Multiple URIs for different resources              │
│           ├── /users, /orders, /products                        │
│           └── Still using single HTTP verb                       │
│                        ↑                                         │
│  Level 0: The Swamp of POX                                      │
│           ├── Single URI for all operations                      │
│           ├── POST /api with action in body                     │
│           └── RPC-style over HTTP                                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

API Design Decision Tree

┌─────────────────────────────────────────────────────────────────┐
│                 Which API Style to Choose?                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Start Here                                                      │
│      │                                                           │
│      ▼                                                           │
│  Public API for third parties?                                  │
│      │                                                           │
│      ├── Yes → REST (with OpenAPI)                              │
│      │         • Easy to understand                              │
│      │         • Good tooling                                    │
│      │         • HTTP caching                                    │
│      │                                                           │
│      └── No → Internal/Microservices?                           │
│               │                                                  │
│               ├── Yes → Need real-time?                         │
│               │         │                                        │
│               │         ├── Yes → gRPC streaming                │
│               │         │                                        │
│               │         └── No → High performance?              │
│               │                  │                               │
│               │                  ├── Yes → gRPC                 │
│               │                  └── No → REST                  │
│               │                                                  │
│               └── No → Mobile/Web frontend?                     │
│                        │                                         │
│                        ├── Multiple clients? → GraphQL          │
│                        ├── Complex queries? → GraphQL           │
│                        └── Simple CRUD? → REST                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Quick Reference

HTTP Methods

Method	Idempotent	Safe	Cacheable	Request Body
GET	Yes	Yes	Yes	No
POST	No	No	No	Yes
PUT	Yes	No	No	Yes
PATCH	No*	No	No	Yes
DELETE	Yes	No	No	Optional

Common Status Codes

Code	Name	Usage
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST (resource created)
204	No Content	Successful DELETE
400	Bad Request	Invalid syntax, validation error
401	Unauthorized	Missing/invalid authentication
403	Forbidden	Valid auth, no permission
404	Not Found	Resource doesn't exist
409	Conflict	Resource conflict
422	Unprocessable	Semantic errors
429	Too Many Requests	Rate limited
500	Internal Error	Server error

Skills Index

REST

Skill	Description
rest-principles	Core REST constraints and design
resource-naming	URI design and resource naming
http-methods	HTTP verb semantics
status-codes	HTTP status code usage
pagination	Pagination strategies
filtering-sorting	Query parameters design
versioning	API versioning approaches

GraphQL

Skill	Description
graphql-basics	GraphQL fundamentals
schema-design	Type system and schema
resolvers	Resolver patterns
mutations	Write operations
subscriptions	Real-time updates

gRPC

Skill	Description
grpc-basics	gRPC fundamentals
protobuf	Protocol Buffers
streaming	Streaming patterns

Documentation

Skill	Description
openapi-swagger	OpenAPI specification
api-documentation	Documentation best practices
examples	Code examples and SDKs

Patterns

Skill	Description
request-response	Request/response design
error-handling	Error handling patterns
authentication	Auth patterns
rate-limiting	Rate limiting strategies
idempotency	Idempotent operations

Best Practices

Skill	Description
api-guidelines	General API guidelines
backwards-compatibility	Maintaining compatibility
api-evolution	Evolving APIs over time

Source

git clone https://github.com/Fujigo-Software/f5-framework-claude/blob/main/plugins/f5-core/skills/api-design/SKILL.mdView on GitHub

Overview

API Design Skills cover REST, GraphQL, and gRPC, plus documentation standards, patterns, and best practices. It helps you build clean, consistent, and developer-friendly APIs and references the Richardson REST Maturity Model to guide evolution.

How This Skill Works

You start by selecting the API model based on the use case (REST for resources, GraphQL for flexible queries, gRPC for high-performance RPC). Then you define contracts using OpenAPI for REST, SDL for GraphQL, and Protocol Buffers (.proto) for gRPC, followed by implementing patterns for requests/responses, errors, pagination, and authentication. GraphQL requires resolvers and subscriptions to address data fetching and the N+1 problem, while REST and gRPC rely on clear schemas and service definitions.

When to Use It

Designing a public REST API for CRUD resources with pagination and standard HTTP semantics.
Building a GraphQL API when clients need flexible, strongly typed queries and real-time updates.
Implementing a gRPC service for internal microservices requiring low latency and streaming.
Documenting APIs with OpenAPI/Swagger for REST or SDL for GraphQL and providing SDKs.
Planning API evolution with versioning, deprecation policies, and backward compatibility.

Quick Start

Step 1: Assess requirements and pick the API style (REST for CRUD, GraphQL for flexible queries, gRPC for low-latency services).
Step 2: Define contracts: REST with OpenAPI, GraphQL with SDL, or gRPC with .proto files.
Step 3: Document and plan evolution: publish docs (OpenAPI/Swagger, GraphQL SDL, or proto docs) and establish a versioning/deprecation strategy.

Best Practices

Start with REST resource naming, HTTP verb semantics, and explicit status codes (200, 201, 404, etc.).
Choose the API model that fits the problem: REST for public CRUD, GraphQL for client-driven queries, gRPC for low-latency internal calls.
Document contracts with appropriate standards: OpenAPI/Swagger for REST, SDL for GraphQL, and .proto for gRPC; include examples and SDKs.
Design pagination, filtering, and sorting; implement consistent error handling, authentication patterns, and idempotency where applicable.
Plan for backward compatibility and evolution: versioning, deprecation policies, and migration paths.

Example Use Cases

Public REST API for an e-commerce catalog with resource-based URIs, pagination, and filtering.
GraphQL API for a social network with typed schemas, queries, mutations, and subscriptions.
gRPC service for internal order processing with streaming updates and protobuf-defined services.
OpenAPI-documented REST API with generated SDKs for external developers.
Versioned API with a clear deprecation path and non-breaking changes in subsequent releases.