melodic-software/api-contract

/api-contract Command

Generate contract-first API specifications from requirements or domain descriptions.

Usage

/api-contract "user registration with email verification"
/api-contract "order events for downstream systems" format=asyncapi
/api-contract "high-performance inventory service" format=protobuf

Workflow

Step 1: Analyze Requirements

Parse the API description to identify:

• Domain entities and resources
• Required operations (CRUD, queries, commands)
• Communication pattern (sync REST, async events, RPC)
• Key consumers and use cases

Step 2: Select Contract Format

If format not specified, auto-detect based on description:

| Pattern | Recommended Format | |---------|-------------------| | "API", "REST", "endpoint" | OpenAPI 3.1 | | "events", "messages", "streaming" | AsyncAPI 3.0 | | "gRPC", "high-performance", "internal" | Protocol Buffers |

Step 3: Invoke Appropriate Skill

Load the relevant skill:

• openapi-design for REST APIs
• asyncapi-design for event-driven APIs
• protobuf-design for gRPC services

Step 4: Design Resource Model

Identify and structure:

• Core entities with properties
• Value objects and enumerations
• Relationships between entities
• Request/response wrappers

Step 5: Generate Contract

Create the API specification including:

• Complete schema definitions
• All operations/methods
• Authentication configuration
• Error response schemas
• Examples for each operation

Step 6: Output Result

Deliver:

1. Contract specification (YAML or .proto)
2. Summary of endpoints/channels/services
3. Implementation notes
4. Suggested test scenarios

Format-Specific Output

OpenAPI 3.1

openapi: 3.1.0
info:
  title: Service Name API
  version: 1.0.0
paths:
  /resources:
    get: ...
    post: ...
components:
  schemas: ...
  securitySchemes: ...

AsyncAPI 3.0

asyncapi: 3.0.0
info:
  title: Service Events
  version: 1.0.0
channels:
  resourceCreated:
    address: resources.created
    messages: ...
components:
  messages: ...
  schemas: ...

Protocol Buffers

syntax = "proto3";
package service.v1;

service ResourceService {
  rpc CreateResource(...) returns (...);
  rpc GetResource(...) returns (...);
}

message Resource {
  string id = 1;
  ...
}

Examples

REST API for User Registration

/api-contract "user registration API with email verification and password reset"

Output:

• OpenAPI 3.1 specification
• POST /users (registration)
• POST /users/verify-email
• POST /users/forgot-password
• POST /users/reset-password
• JWT authentication scheme

Event-Driven Order System

/api-contract "order lifecycle events for fulfillment and notifications" format=asyncapi

Output:

• AsyncAPI 3.0 specification
• Channels: orders.created, orders.submitted, orders.shipped
• CloudEvents envelope
• Kafka bindings

gRPC Product Catalog

/api-contract "product catalog service with search and inventory" format=protobuf

Output:

• Protocol Buffers definition
• ProductService with CRUD + Search
• Streaming for bulk operations
• Well-known types for timestamps

Integration

The command integrates with:

• requirements-elicitation: Uses functional requirements
• enterprise-architecture: Aligns with bounded contexts
• test-strategy: Generates contract test scenarios
• systems-design: Follows API design patterns