skills.rest
roanbrasil
roanbrasilCOMMUNITY
Explore all skills by this author →
Website𝕏@roanbrasilGitHub

api-contract-design

Design REST, gRPC, and GraphQL API contracts with OpenAPI 3.1 and Protobuf.

5|1|Updated Jun 17, 2026
Search Tags:#openapi#graphql#contract-testing#grpc#api-design#rest-api#api-versioning
One-click install
npx skills add https://github.com/roanbrasil/engineer-grade-agent-skills --skill api-contract-design-roanbrasil
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-contract-design
Source: https://github.com/roanbrasil/engineer-grade-agent-skills/tree/main/skills/api-contract-design
Command: npx skills add https://github.com/roanbrasil/engineer-grade-agent-skills --skill api-contract-design-roanbrasil

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill solves the common pain point of inconsistent, poorly documented, or breaking API changes that cause integration failures, consumer downtime, and costly rework across development teams and external partners.

Core Features & Use Cases

  • Multi-Protocol API Design: Covers REST (OpenAPI 3.1), gRPC (Protobuf), and GraphQL schema authoring with idiomatic, production-grade patterns for each.
  • Stability & Compatibility: Provides versioning strategies, breaking vs non-breaking change rules, and Protobuf schema evolution guidelines to maintain backward compatibility.
  • Contract Testing & Validation: Includes consumer-driven contract testing with Pact, RFC 7807 error formatting, idempotency handling, and pagination best practices to catch issues before deployment.
  • Use Case Example: A team building a microservices e-commerce platform uses this Skill to design consistent order, payment, and customer APIs, preventing breaking changes that would crash mobile apps or partner integrations.

Quick Start

Use the api-contract-design skill to create a complete OpenAPI 3.1 specification for your new order management API, including versioning, error handling, and pagination rules.

Frequently Asked Questions about api-contract-design

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

FAQPage Schema
How do I design an OpenAPI 3.1 specification for a microservices e-commerce platform?▼

To design an OpenAPI 3.1 specification for microservices, you define production-grade API contracts covering versioning, error handling, and pagination rules to prevent breaking changes and ensure cross-team integration stability.

What is the best way to maintain Protobuf schema backward compatibility during gRPC API versioning?▼

Maintaining Protobuf schema backward compatibility requires applying safe schema evolution guidelines and distinguishing between breaking vs non-breaking changes to prevent consumer downtime in gRPC API versioning.

How does consumer-driven contract testing with Pact work for REST and gRPC?▼

Consumer-driven contract testing with Pact works by validating REST and gRPC interactions against predefined contracts, catching integration failures and idempotency issues before deployment through automated testing.

Can I use RFC 7807 error formatting and cursor-based pagination in GraphQL schemas?▼

Yes, you can implement RFC 7807 error formatting and cursor-based pagination in GraphQL schemas to standardize error responses and manage large datasets efficiently across multi-protocol API designs.

Why do I need API contract design for public API releases and microservice communication?▼

You need API contract design for public API releases and microservice communication to eliminate integration failures, reduce manual documentation effort, and enforce contract stability critical for external partner integrations.

Related Skills

Explore More Software Engineering Skills→
musujmusuj

phase-1-schema

Define project terminology, entities, relationships, and data structures.

Community
Intermediate
ccfccf

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from design or code sources.

Community
Advanced
mariotoffiamariotoffia

setup-contract-tests

Automate contract testing setup for microservices using OpenAPI and JSON Schema.

Community
Advanced
berea-chberea-ch

extract-openapi-from-code

Extract OpenAPI specifications from API codebases in JSON or YAML.

Official
Advanced