TypeSpec API Operations

An AI skill that generates TypeSpec API operation definitions, helping developers define type safe HTTP endpoints, request and response models, and API contracts using the TypeSpec language for consistent API design across services.

What Is This?

Overview

This skill creates TypeSpec operation definitions that describe HTTP API endpoints with full type information. TypeSpec is a language for defining API contracts that compiles to OpenAPI, JSON Schema, and client SDKs. The skill generates model definitions, operation signatures, parameter bindings, response types, and error handling patterns. The output serves as the single source of truth for your API contract, from which documentation and client code are generated automatically.

Who Should Use This

Designed for API developers adopting TypeSpec for contract first development, teams building services that need consistent API definitions across multiple languages, and organizations standardizing API design patterns through shared TypeSpec libraries.

Why Use It?

Problems It Solves

Defining APIs through code or documentation alone leads to inconsistencies between what the API promises and what it delivers. OpenAPI specs written by hand drift from implementation. TypeSpec solves this by providing a concise language for API contracts, but learning its syntax and patterns takes time. This skill generates correct TypeSpec from natural language descriptions.

Core Highlights

• Operation Generation creates complete endpoint definitions with typed parameters
• Model Definition generates request and response types with validation rules
• Error Patterns implements consistent error response types across operations
• Decorator Usage applies appropriate TypeSpec decorators for HTTP bindings
• Namespace Organization structures operations into logical service groups

How to Use It?

Basic Usage

Describe your API endpoints and receive complete TypeSpec operation definitions.

// Generated: main.tsp
import "@typespec/http";
import "@typespec/rest";

using TypeSpec.Http;
using TypeSpec.Rest;

model User {
  @key id: string;
  name: string;
  email: string;
  @visibility("read") createdAt: utcDateTime;
}

model UserCreate {
  name: string;
  email: string;
}

@route("/users")
namespace Users {
  @get op list(@query limit?: int32 = 20): User[];
  @get op read(@path id: string): User | NotFoundResponse;
  @post op create(@body user: UserCreate): User;
}

Real-World Examples

E-Commerce API Contract

A team designing a product catalog API used this skill to generate TypeSpec definitions for their entire service. The generated contract covered product CRUD operations, search with pagination, category filtering, and inventory checks. From this single TypeSpec file, they generated OpenAPI docs, TypeScript client SDK, and server stubs.

// Generated: product-service.tsp
model Product {
  @key id: string;
  name: string;
  price: float64;
  category: string;
  inStock: boolean;
}

model ProductListResponse {
  items: Product[];
  total: int32;
  page: int32;
}

@route("/products")
namespace Products {
  @get op list(
    @query category?: string,
    @query page?: int32 = 1,
    @query limit?: int32 = 20
  ): ProductListResponse;

  @get op read(@path id: string): Product | NotFoundResponse;
  @put op update(@path id: string, @body product: Product): Product;
}

Advanced Tips

Use TypeSpec libraries to share common models and error types across multiple services. Leverage the compiler API to generate custom output formats beyond OpenAPI. Set up TypeSpec compilation in CI to catch contract changes before they reach production.

When to Use It?

Use Cases

• Contract First Development define API contracts before writing implementation
• Multi Service APIs maintain consistent patterns across microservices
• SDK Generation produce type safe client libraries from API definitions
• Documentation generate always accurate OpenAPI specs from TypeSpec source
• API Governance enforce organization wide API design standards

Related Topics

When working with TypeSpec APIs, these prompts activate the skill:

• "Generate TypeSpec operations for my API"
• "Define API models in TypeSpec"
• "Create a TypeSpec contract for this service"
• "Write TypeSpec definitions for CRUD endpoints"

Important Notes

Requirements

• TypeSpec compiler installed via npm for compilation
• Understanding of HTTP API design principles
• Target output format selected like OpenAPI 3.0 or JSON Schema
• Works with any backend language that can consume the generated specs

Usage Recommendations

Do:

• Use TypeSpec as the single source of truth for your API contract
• Compile and validate generated definitions before sharing with teams
• Share common models across services using TypeSpec libraries
• Version your API contracts in source control alongside implementation

Don't:

• Manually edit generated OpenAPI output as changes will be overwritten
• Skip validation decorators since they document and enforce constraints
• Define operations without error types as clients need to handle failures
• Ignore breaking change detection when modifying existing contracts

Limitations

• TypeSpec is a newer language with a smaller community than OpenAPI directly
• Some advanced OpenAPI features may require custom TypeSpec emitter configuration
• Generated output format depends on the TypeSpec emitter version installed
• Complex API patterns like webhooks or streaming may need manual TypeSpec authoring