Api Designer

Streamline API design workflows with automated schema generation and integration tools

Category: development Source: Jeffallan/claude-skills

Api Designer is a community skill for designing RESTful and GraphQL APIs from requirements, covering resource modeling, endpoint design, schema definition, authentication patterns, and API specification generation for consistent and scalable interfaces.

What Is This?

Overview

Api Designer provides patterns for translating business requirements into well-structured API specifications. It covers resource modeling that identifies entities, relationships, and actions to define API resources and sub-resources, endpoint design that maps CRUD operations and custom actions to HTTP methods and URL patterns, schema definition that creates request and response payloads with proper data types, validation, and documentation, authentication patterns that integrate OAuth 2.0, API keys, and JWT into endpoint security, and specification generation that outputs OpenAPI 3.0 documents from design decisions. The skill enables backend teams to design APIs that are consistent, documented, and ready for implementation.

Who Should Use This

This skill serves backend engineers designing new APIs from product requirements, architects defining API contracts between frontend and backend teams, and technical leads establishing API patterns for new microservices.

Why Use It?

Problems It Solves

Starting API design without structure leads to inconsistent naming and endpoint organization. Frontend and backend teams disagree on contracts when designs are not formalized upfront. Resource relationships become tangled when not modeled before endpoint creation. API documentation is written as an afterthought and diverges from actual behavior.

Core Highlights

Resource modeler maps domain entities to API resources with proper nesting. Endpoint generator creates HTTP method and URL combinations from resource actions. Schema builder defines typed request and response objects with validation rules. OpenAPI generator produces specification files from design decisions.

How to Use It?

Basic Usage

openapi: '3.0.3'
info:
  title: Task Manager API
  version: '1.0.0'
  description: |
    API for managing tasks
    and projects.

paths:
  /projects:
    get:
      summary: List projects
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/\
                  schemas/\
                  ProjectList'
    post:
      summary: Create project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/\
                schemas/\
                CreateProject'
      responses:
        '201':
          description: Created

Real-World Examples

// API design from requirements
interface ResourceModel {
  name: string;
  fields: Field[];
  relations: Relation[];
  actions: Action[];
}

interface Field {
  name: string;
  type: string;
  required: boolean;
  validation?: string;
}

interface Relation {
  target: string;
  type: 'hasMany'
    | 'belongsTo'
    | 'manyToMany';
}

function generateEndpoints(
  model: ResourceModel
): Endpoint[] {
  const base = `/${model.name
    .toLowerCase()}s`;
  const endpoints: Endpoint[] =
    [
      { method: 'GET',
        path: base,
        desc: `List ${model
          .name}s` },
      { method: 'POST',
        path: base,
        desc: `Create ${model
          .name}` },
      { method: 'GET',
        path: `${base}/{id}`,
        desc: `Get ${model
          .name}` },
      { method: 'PUT',
        path: `${base}/{id}`,
        desc: `Update ${model
          .name}` },
      { method: 'DELETE',
        path: `${base}/{id}`,
        desc: `Delete ${model
          .name}` },
    ];

  // Add relation endpoints
  for (const rel
      of model.relations) {
    if (rel.type ===
        'hasMany') {
      endpoints.push({
        method: 'GET',
        path: `${base}/{id}`
          + `/${rel.target}s`,
        desc: `List ${rel
          .target}s`,
      });
    }
  }
  return endpoints;
}

Advanced Tips

Design APIs contract-first by writing the OpenAPI specification before any implementation code to align frontend and backend teams early. Use discriminator fields in response schemas for polymorphic resources that share a base type. Define reusable pagination and error schemas as shared components referenced across all endpoints.

When to Use It?

Use Cases

Design a REST API for a new microservice based on product requirements and domain models. Generate an OpenAPI specification for contract-first development with frontend teams. Model resource relationships and generate nested endpoint structures for complex domain models.

Related Topics

API design, REST architecture, OpenAPI specification, resource modeling, and contract-first development.

Important Notes

Requirements

Domain requirements document describing entities and their relationships. OpenAPI editor or validator for specification authoring. Team agreement on naming conventions and pagination standards.

Usage Recommendations

Do: model resources and relationships before designing individual endpoints. Use consistent naming with plural resource nouns and standard HTTP methods. Include pagination parameters on all list endpoints from the initial design.

Don't: design endpoints ad-hoc without a resource model leading to inconsistent URL structures. Use verbs in endpoint paths like /getUsers instead of proper HTTP method semantics. Skip error response schema design which causes inconsistent error handling.

Limitations

Generated specifications may need manual refinement for complex business logic endpoints. Resource modeling works best for CRUD-oriented domains and may not fit event-driven or RPC-style APIs. OpenAPI specifications cannot fully express runtime behavior like rate limiting or webhook delivery.