skills.rest
bbara04
bbara04COMMUNITY
Explore all skills by this author →
GitHub

designing-apis

Guide REST and GraphQL API contract design with endpoint patterns and schema structure.

Updated May 18, 2026
Search Tags:#versioning#error handling#api design#openapi#rest#graphql#http status codes
One-click install
npx skills add https://github.com/bbara04/openchamber-complete --skill designing-apis-bbara04
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: designing-apis
Source: https://github.com/bbara04/openchamber-complete/tree/main/opencode-config/skill/designing-apis
Command: npx skills add https://github.com/bbara04/openchamber-complete --skill designing-apis-bbara04

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents poorly designed APIs by providing clear, reusable patterns for endpoints, schemas, versioning, and error handling.

Core Features & Use Cases

  • REST endpoint design: Resource-oriented URL structures, correct HTTP method semantics, request/response patterns, and pagination/filtering conventions.
  • Request and response contract quality: Consistent response envelopes with predictable error formats and status-code decision guidance.
  • GraphQL schema design: Schema-first GraphQL types, input patterns, and practical pagination strategies.
  • API evolution and governance: Versioning strategies plus authentication/authorization and documentation structures (e.g., OpenAPI).

Quick Start

Ask the AI to design a REST and GraphQL API contract for a “tasks” system (including endpoint paths, request/response JSON schemas, error responses, versioning choice, and a basic GraphQL schema) following clean API best practices.

Frequently Asked Questions about designing-apis

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

FAQPage Schema
How do I design a REST API with consistent endpoint patterns and error handling?▼

Design REST APIs using resource-oriented URL structures, safe HTTP method semantics, and standardized error envelopes. Consistent API design requires clear routing conventions, predictable response schemas, and correct HTTP status codes for maintainable endpoint behavior.

What is the best way to structure a GraphQL schema for pagination and input types?▼

Structure GraphQL schemas using schema-first type definitions, practical pagination strategies, and clear input patterns. Good GraphQL schema design ensures predictable query behavior and supports API evolution through consistent type structures.

How do I choose an API versioning strategy for evolving REST and GraphQL contracts?▼

Choose API versioning strategies based on your evolution needs and governance requirements. Proper versioning for REST and GraphQL APIs prevents breaking changes by applying consistent schema patterns and supporting predictable endpoint behavior over time.

Can I use OpenAPI documentation for both REST and GraphQL API contract reviews?▼

OpenAPI documentation structures support REST API contract design and reviews by standardizing endpoint patterns, request and response schemas, authentication, and error handling. GraphQL schemas use separate schema-first definitions for their contract specifications.

What HTTP status codes should I use for standardized API error handling?▼

Use HTTP status codes that apply safe HTTP semantics for standardized API error handling. Consistent response envelopes require predictable error formats and status-code decision guidance to ensure maintainable endpoint behavior.

How do I implement authentication and authorization in a new API contract?▼

Implement authentication and authorization in new API contracts by defining clear access control patterns within your design. API governance requires consistent security structures across REST and GraphQL endpoints to maintain predictable and safe endpoint behavior.

Related Skills

Explore More Software Engineering Skills→
Olu-AnuAkin-AkinyemiOlu-AnuAkin-Akinyemi
1

api-design-architect

Design RESTful APIs with endpoint planning, authentication patterns, and OpenAPI documentation.

Community
Intermediate
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
michaelsvanbeekmichaelsvanbeek
1

api-design

Define REST API design patterns and contract standards for endpoints and OpenAPI documentation.

Community
Advanced
SaturateSaturate

api-design

Generate OpenAPI specs and TypeScript types from contract-first API designs.

Community
Advanced