skills.rest
HCMUTE-RTIC
HCMUTE-RTICOFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Guide RESTful and GraphQL API design with best practices for schemas, pagination, and errors.

Updated Feb 21, 2026
Search Tags:#schema design#api design#rest#developer experience#graphql#api best practices
One-click install
npx skills add https://github.com/HCMUTE-RTIC/fit-hcmute --skill api-design-principles-hcmute-rtic
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/HCMUTE-RTIC/fit-hcmute/tree/main/.agent/skills/api-design-principles
Command: npx skills add https://github.com/HCMUTE-RTIC/fit-hcmute --skill api-design-principles-hcmute-rtic

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This Skill helps developers design, review, and standardize intuitive, scalable, and maintainable REST and GraphQL APIs, improving developer experience and reducing integration friction.

Core Features & Use Cases

  • RESTful Design: Learn resource-oriented architecture, HTTP method semantics, and best practices for endpoints, pagination, and error handling.
  • GraphQL Design: Understand schema-first development, query/mutation patterns, and N+1 problem solutions with DataLoaders.
  • Use Case: A team is starting a new microservice and needs to define its public API. They use this Skill to ensure the API adheres to best practices for consistency, performance, and developer usability before implementation.

Quick Start

Use the api-design-principles skill to generate a checklist for reviewing a new REST API specification.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
What are the best practices for RESTful API resource orientation and HTTP semantics?▼

RESTful API design relies on resource-oriented architecture and proper HTTP method semantics for endpoints, pagination, and error handling. This approach ensures robust, scalable, and developer-friendly APIs with reduced integration friction.

How do I design a GraphQL schema to avoid the N+1 problem?▼

Designing a GraphQL schema to avoid the N+1 problem requires a schema-first approach and implementing DataLoaders for query and mutation patterns. This batches and caches data requests, optimizing performance and maintainability.

What is the best way to standardize API error handling and versioning?▼

Standardizing API error handling and versioning requires applying consistent design principles across REST and GraphQL schemas. This creates developer-friendly interfaces, prevents common pitfalls, and ensures maintainable public API specifications.

How do I generate a checklist for reviewing a new REST API specification?▼

To generate a checklist for reviewing a new REST API specification, apply comprehensive guidance on resource orientation, HTTP semantics, pagination, and error handling. This verifies adherence to best practices before implementation begins.

Does this API design guidance apply to microservices and public APIs?▼

Yes, this API design guidance applies to microservices and public APIs by providing actionable advice for creating consistent, performant, and developer-friendly interfaces. It ensures new microservice APIs adhere to scalable design principles.

When should I choose GraphQL schema-first development over REST for my API?▼

Choose GraphQL schema-first development over REST when you need flexible query patterns and want to solve data fetching issues like the N+1 problem with DataLoaders. REST remains ideal for standard resource-oriented endpoints and HTTP semantics.

Related Skills

Explore More Software Engineering Skills→
sigmadigitalzasigmadigitalza
1

api-design-review

Review REST and GraphQL API designs for quality and compatibility issues.

Official
Advanced
JaiminVadadoriyaJaiminVadadoriya
1

api-testing

Automate REST and GraphQL API tests with schema validation and authentication.

Community
Advanced
ignidusignidus

api-design

Standardize REST API naming, HTTP semantics, pagination, and versioning rules.

Official
Advanced
rkz91rkz91
264

api-design-principles

Standardize REST and GraphQL API design with schema-first patterns.

Community
Advanced