skills.rest
ftnilsson
ftnilssonCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

API Design

Design REST, GraphQL, and gRPC APIs with resource modeling and versioning.

Updated Feb 15, 2026
Search Tags:#api design#rest#graphql#backend development#grpc#api best practices
One-click install
npx skills add https://github.com/ftnilsson/agent-cli --skill api-design-ftnilsson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: API Design
Source: https://github.com/ftnilsson/agent-cli/tree/main/backend/skills/01-api-design
Command: npx skills add https://github.com/ftnilsson/agent-cli --skill api-design-ftnilsson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps developers design, structure, and evolve backend APIs that are consistent, intuitive, and resilient to change, reducing integration friction and maintenance overhead.

Core Features & Use Cases

  • Resource Modeling: Design APIs around nouns (resources) rather than verbs (actions).
  • Consistent URL Patterns: Enforces conventions for plural nouns, kebab-case, and nesting depth.
  • HTTP Method & Status Code Guidance: Correctly applies HTTP verbs and status codes for predictable interactions.
  • Standardized Error Responses: Defines a clear, machine-readable error format.
  • Pagination Strategies: Implements cursor-based or offset-based pagination for collections.
  • Versioning: Provides strategies for evolving APIs without breaking changes.
  • Documentation Best Practices: Emphasizes OpenAPI/Swagger, examples, and changelogs.
  • Use Case: When designing a new /users endpoint, this skill guides you on how to structure the URLs, handle requests for listing users, creating a user, retrieving a specific user, and updating their profile, ensuring consistency with other API resources.

Quick Start

Use the API Design skill to create a consistent URL pattern for a new /products collection endpoint.

Frequently Asked Questions about API Design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a REST API for consistent resource modeling and URL design?▼

REST API design structures endpoints around plural nouns rather than verbs, enforcing kebab-case and consistent nesting depth. This approach minimizes integration friction by making resource interactions predictable and maintaining uniform URL patterns across the entire backend API.

What is the best way to handle API versioning without breaking existing contracts?▼

API versioning evolves backend interfaces without introducing breaking changes to existing contracts. It provides specific strategies for managing updates, ensuring maintainability and seamless integration while preserving backward compatibility for current API consumers.

How do I standardize API error responses and HTTP status codes?▼

Standardizing API error responses involves defining a clear, machine-readable error format and applying HTTP status codes correctly. This ensures predictable API interactions, allowing clients to handle failures consistently and developers to debug issues faster.

When should I use cursor-based pagination instead of offset-based pagination for collections?▼

Cursor-based pagination is needed when handling large or frequently changing data collections in an API. Unlike offset-based pagination, cursors provide stable results by using data pointers, preventing duplicate or missing records during backend data shifts.

Does this API design approach work for both GraphQL and gRPC protocols?▼

Yes, this API design approach structures and evolves backend APIs across REST, GraphQL, and gRPC protocols. It addresses common pitfalls and ensures consistency, discoverability, and maintainability regardless of the specific communication protocol used.

How do I document API best practices using OpenAPI and Swagger?▼

Documenting API best practices emphasizes using OpenAPI and Swagger to define contracts, provide clear examples, and maintain changelogs. This ensures the API is discoverable, machine-readable, and easy for developers to integrate and maintain.

Related Skills

Explore More Software Engineering Skills→
bovinphangbovinphang
21

fec-backend-requirements-handoff

Document frontend data, actions, state, and validation rules for backend review.

Community
Intermediate
686f6c61686f6c61
105

api-docs

Generate API documentation with HTTP methods, routes, parameters, and schemas.

Community
Intermediate
dpieterszdpietersz

Backend API

Design RESTful API endpoints, controllers, and middleware for scalable web services.

Community
Intermediate
manutejmanutej
1

graphql-api-development

Develop GraphQL APIs with schemas, resolvers, and subscriptions on Node.js and Express.

Community
Advanced