Skip to content

API Designer

Jump to bottom
j0KZ edited this page Oct 9, 2025 · 3 revisions

API Designer

Design REST and GraphQL APIs with OpenAPI generation.

npm version

Overview

API Designer helps you design REST and GraphQL APIs following best practices, generate OpenAPI 3.0 specifications, create API client code, and validate API designs.

Key Features:

  • API design - Create REST and GraphQL APIs from requirements
  • OpenAPI generation - Auto-generate Swagger/OpenAPI specs
  • Best practices - RESTful conventions, versioning, error handling
  • Client generation - Generate client code in multiple languages
  • Mock server - Create mock servers for testing

💡 How to Use

Just ask naturally in your editor - works in English and Spanish:

Design a REST API (English / Español)

"Design a REST API for a blog with users, posts, and comments"
"Diseñar una API REST para un blog con usuarios, posts y comentarios"

What You Get

✓ REST API Design Complete:

📋 Generated Endpoints:

Users:
  GET    /v1/users              - List users (paginated)
  POST   /v1/users              - Create user
  GET    /v1/users/{id}         - Get user
  PUT    /v1/users/{id}         - Update user
  DELETE /v1/users/{id}         - Delete user

Posts:
  GET    /v1/posts              - List posts
  POST   /v1/posts              - Create post
  GET    /v1/posts/{id}         - Get post
  PUT    /v1/posts/{id}         - Update post
  DELETE /v1/posts/{id}         - Delete post
  GET    /v1/posts/{id}/comments - Get post comments

Comments:
  GET    /v1/comments           - List comments
  POST   /v1/comments           - Create comment
  GET    /v1/comments/{id}      - Get comment
  DELETE /v1/comments/{id}      - Delete comment

✅ Features: Pagination, versioning, error handling
📄 OpenAPI 3.0 spec generated

Generate Client Code (English / Español)

"Generate TypeScript client for this API"
"Generar cliente TypeScript para esta API"

What You Get

✓ TypeScript Client Generated:

// Auto-generated API client
import { ApiClient } from './api-client';

const client = new ApiClient('https://api.example.com');

// Full type safety
const users = await client.users.list({ page: 1, limit: 20 });
const user = await client.users.get('user-id');
const newPost = await client.posts.create({
  title: 'Hello World',
  content: '...',
  authorId: user.id
});

✅ Features:
  - Full TypeScript types
  - Async/await support
  - Error handling
  - Request/response validation
  - Axios integration

Create GraphQL Schema (English / Español)

"Design a GraphQL schema for an e-commerce platform"
"Diseñar un esquema GraphQL para una plataforma de comercio electrónico"

What You Get

✓ GraphQL Schema Generated:

type Product {
  id: ID!
  name: String!
  description: String
  price: Float!
  category: Category!
  inventory: Int!
}

type Category {
  id: ID!
  name: String!
  products: [Product!]!
}

type Order {
  id: ID!
  user: User!
  products: [Product!]!
  total: Float!
  status: OrderStatus!
}

type Query {
  product(id: ID!): Product
  products(category: ID, limit: Int): [Product!]!
  order(id: ID!): Order
  userOrders(userId: ID!): [Order!]!
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order!
  updateOrderStatus(id: ID!, status: OrderStatus!): Order!
}

Validate API Design (English / Español)

"Check if this API follows REST best practices"
"Verificar si esta API sigue las mejores prácticas REST"

What You Get

⚠️  API Design Validation Results:

❌ Issues Found (3):

1. CRITICAL - Missing Versioning
   Endpoints should include version: /v1/users
   Impact: Breaking changes will affect clients

2. HIGH - Inconsistent Naming
   Found mixed casing: camelCase and snake_case
   Recommendation: Use consistent camelCase

3. MEDIUM - Pagination Not Implemented
   List endpoints should support pagination
   Add: ?page=1&limit=20

✅ Good Practices Found:
  - Proper HTTP methods (GET, POST, PUT, DELETE)
  - Resource-based endpoints
  - Status codes properly defined
  - Authentication configured

🔧 Available Tools

generate_openapi

Generate OpenAPI 3.0 specification from API configuration.

Parameters:

  • config (required) - API design configuration
    • name - API name
    • version - API version
    • style - 'REST' | 'GraphQL' | 'gRPC' | 'WebSocket'
    • resources - Resource names array
    • auth - Authentication configuration
  • endpoints (optional) - Custom REST endpoints

design_rest_api

Design RESTful API endpoints following best practices.

Parameters:

  • resources (required) - Resource names to generate endpoints for
  • config (required) - API configuration

create_graphql_schema

Create GraphQL schema with types, queries, mutations.

Parameters:

  • config (required) - API configuration
  • customTypes (optional) - Custom GraphQL type definitions

generate_client

Generate API client code in various languages.

Parameters:

  • spec (required) - OpenAPI specification or GraphQL schema
  • options (required) - Client generation options
    • language - Target language (TypeScript, Python, Java, etc.)
    • outputFormat - HTTP client library
    • includeTypes - Include type definitions

validate_api

Validate API design against best practices.

Parameters:

  • spec (required) - OpenAPI specification or GraphQL schema

generate_mock_server

Generate mock server code for testing.

Parameters:

  • spec (required) - OpenAPI specification
  • config (optional) - Mock server configuration

💡 Best Practices

Always Version Your API

"Design API with versioning: /v1/users"
"Diseñar API con versionado: /v1/users"

Implement Pagination

"Add pagination support to all list endpoints"
"Agregar soporte de paginación a todos los endpoints de listado"

Document Everything

"Generate OpenAPI spec with examples for all endpoints"
"Generar especificación OpenAPI con ejemplos para todos los endpoints"

🔗 Related Tools

Combine with other tools for powerful workflows:

📚 Learn More

Need help? Open an issue | View documentation

Clone this wiki locally