Rozwój API z AI

Przyspiesz rozwój API od projektowania do wdrożenia z pomocą AI, które rozumie nowoczesne wzorce API i najlepsze praktyki.

Rozwój API wspomagany przez AI

Podejście design-first

Generuj schematy OpenAPI/GraphQL z wymagań, zapewniając spójny design API we wszystkich serwisach.

Szybkość implementacji

Przekształcaj specyfikacje API w działający kod z odpowiednią walidacją, obsługą błędów i dokumentacją.

Automatyzacja testowania

Generuj kompleksowe zestawy testów włącznie z testami jednostkowymi, integracyjnymi i kontraktowymi.

Dokumentacja

Utrzymuj zawsze aktualną dokumentację API z przykładami, SDK i interaktywnymi playground’ami.

Projektowanie API z AI

Projektowanie REST API

Wymagania do OpenAPI

# Język naturalny do OpenAPI
"Zaprojektuj REST API dla systemu zarządzania zadaniami:
- Operacje CRUD dla zadań
- Uwierzytelnianie użytkowników
- Przypisywanie zadań i aktualizacje statusu
- Filtrowanie i paginacja
- Przestrzegaj najlepszych praktyk REST"

# AI generuje specyfikację OpenAPI 3.0:
openapi: 3.0.0
info:
  title: Task Management API
  version: 1.0.0
paths:
  /tasks:
    get:
      summary: Lista zadań
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [todo, in_progress, done]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        200:
          description: Spaginowana lista zadań
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'

Modelowanie zasobów

"Zaprojektuj zasoby RESTful dla e-commerce:
- Przestrzegaj poziomu dojrzałości REST 3 (HATEOAS)
- Odpowiednie metody HTTP i kody statusu
- Relacje między zasobami
- Strategia wersjonowania"

Generowanie implementacji

// Generuj z OpenAPI
"Zaimplementuj endpoint API zadań:
- Express.js z TypeScript
- Walidacja wejścia
- Obsługa błędów
- Integracja z bazą danych
- Middleware uwierzytelniania"

// AI generuje:
import { Router } from 'express';
import { body, query, validationResult } from 'express-validator';

const router = Router();

router.get('/tasks',
  authenticate,
  query('status').optional().isIn(['todo', 'in_progress', 'done']),
  query('page').optional().isInt({ min: 1 }),
  async (req, res) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }

    const { status, page = 1 } = req.query;
    const tasks = await taskService.list({
      status,
      page,
      userId: req.user.id
    });

    res.json({
      data: tasks,
      links: generatePaginationLinks(req, tasks.totalPages)
    });
  }
);

# Generuj schemat GraphQL
"Zaprojektuj GraphQL API dla platformy blogowej:
- Posty, autorzy, komentarze
- Subskrypcje w czasie rzeczywistym
- Złożone filtrowanie
- Paginacja w stylu Relay"

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments(first: Int, after: String): CommentConnection!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Query {
  post(id: ID!): Post
  posts(
    filter: PostFilter
    first: Int
    after: String
  ): PostConnection!
}

type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
  updatePost(input: UpdatePostInput!): UpdatePostPayload!
}

type Subscription {
  postUpdated(id: ID!): Post!
  commentAdded(postId: ID!): Comment!
}

// Generuj resolvery
"Zaimplementuj resolvery GraphQL z:
- DataLoader dla zapobiegania N+1
- Uwierzytelnianie/autoryzacja
- Obsługa błędów
- Wsparcie subskrypcji"

const resolvers = {
  Query: {
    posts: async (_, { filter, first, after }, { dataSources, user }) => {
      checkAuth(user);

      const posts = await dataSources.postAPI.getPosts({
        filter,
        first: first || 20,
        after: decodeCursor(after)
      });

      return {
        edges: posts.map(post => ({
          node: post,
          cursor: encodeCursor(post.id)
        })),
        pageInfo: {
          hasNextPage: posts.hasNext,
          endCursor: posts.length ? encodeCursor(posts[posts.length - 1].id) : null
        }
      };
    }
  },

  Post: {
    author: (post, _, { loaders }) => loaders.userLoader.load(post.authorId),
    comments: (post, args) => getComments(post.id, args)
  },

  Subscription: {
    postUpdated: {
      subscribe: withFilter(
        () => pubsub.asyncIterator(['POST_UPDATED']),
        (payload, variables) => payload.postUpdated.id === variables.id
      )
    }
  }
};

Projektowanie gRPC API

Definicja Protocol Buffer

# Generuj pliki proto
"Zaprojektuj serwis gRPC dla zarządzania użytkownikami:
- Operacje CRUD użytkowników
- Streaming dla operacji masowych
- Maski pól dla częściowych aktualizacji
- Obsługa błędów"

syntax = "proto3";

package user.v1;

import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);

  // Streaming
  rpc StreamUsers(StreamUsersRequest) returns (stream User);
  rpc BulkCreateUsers(stream CreateUserRequest) returns (BulkCreateUsersResponse);
}

message User {
  string id = 1;
  string email = 2;
  string name = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Timestamp updated_at = 5;
}

message UpdateUserRequest {
  string id = 1;
  User user = 2;
  google.protobuf.FieldMask field_mask = 3;
}

Wzorce implementacji API

Uwierzytelnianie i autoryzacja

# Generuj middleware uwierzytelniania
"Zaimplementuj uwierzytelnianie JWT z:
- Generowanie i walidacja tokenów
- Rotacja refresh tokenów
- Kontrola dostępu oparta na rolach
- Zarządzanie kluczami API
- Integracja OAuth2"

// Middleware JWT
export const authenticate = async (req: Request, res: Response, next: NextFunction) => {
  try {
    const token = extractToken(req);
    if (!token) {
      return res.status(401).json({ error: 'Wymagane uwierzytelnianie' });
    }

    const payload = await verifyToken(token);
    const user = await userService.findById(payload.userId);

    if (!user || user.deletedAt) {
      return res.status(401).json({ error: 'Nieprawidłowy token' });
    }

    req.user = user;
    next();
  } catch (error) {
    if (error.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token wygasł' });
    }
    return res.status(401).json({ error: 'Nieprawidłowy token' });
  }
};

// Autoryzacja oparta na rolach
export const authorize = (...roles: string[]) => {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Wymagane uwierzytelnianie' });
    }

    if (!roles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Niewystarczające uprawnienia' });
    }

    next();
  };
};

Obsługa błędów

Błędy REST
Błędy GraphQL

// Spójne odpowiedzi błędów
"Utwórz middleware obsługi błędów:
- Standardowy format błędów
- Odpowiednie kody statusu HTTP
- Logowanie błędów
- Wiadomości przyjazne klientowi"

class APIError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public code?: string,
    public details?: any
  ) {
    super(message);
  }
}

const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
  logger.error(err);

  if (err instanceof APIError) {
    return res.status(err.statusCode).json({
      error: {
        message: err.message,
        code: err.code,
        details: err.details
      }
    });
  }

  if (err.name === 'ValidationError') {
    return res.status(400).json({
      error: {
        message: 'Walidacja nie powiodła się',
        code: 'VALIDATION_ERROR',
        details: extractValidationErrors(err)
      }
    });
  }

  res.status(500).json({
    error: {
      message: 'Błąd wewnętrzny serwera',
      code: 'INTERNAL_ERROR'
    }
  });
};

// Obsługa błędów GraphQL
"Zaimplementuj formatowanie błędów GraphQL:
- Wiadomości przyjazne użytkownikowi
- Kody błędów
- Błędy na poziomie pól
- Rozszerzenia błędów"

const formatError = (error: GraphQLError) => {
  const { message, extensions, path } = error;

  // Loguj błędy serwera
  if (extensions?.code === 'INTERNAL_SERVER_ERROR') {
    logger.error(error);
    return {
      message: 'Wystąpił błąd',
      extensions: {
        code: 'INTERNAL_ERROR'
      }
    };
  }

  return {
    message,
    path,
    extensions: {
      code: extensions?.code || 'UNKNOWN_ERROR',
      timestamp: new Date().toISOString()
    }
  };
};

Testowanie API

Generowanie testów

Testy jednostkowe

# Generuj testy jednostkowe
"Utwórz testy jednostkowe dla TaskService:
- Mockowanie zależności
- Testowanie wszystkich metod
- Przypadki brzegowe
- Scenariusze błędów"

describe('TaskService', () => {
  let taskService: TaskService;
  let mockRepo: jest.Mocked<TaskRepository>;

  beforeEach(() => {
    mockRepo = createMockRepository();
    taskService = new TaskService(mockRepo);
  });

  describe('createTask', () => {
    it('powinien utworzyć zadanie z prawidłowymi danymi', async () => {
      const input = { title: 'Test Task', userId: '123' };
      mockRepo.create.mockResolvedValue({ id: '1', ...input });

      const result = await taskService.createTask(input);

      expect(result).toMatchObject(input);
      expect(mockRepo.create).toHaveBeenCalledWith(input);
    });

    it('powinien rzucić błąd przy duplikacie tytułu', async () => {
      mockRepo.create.mockRejectedValue(new UniqueConstraintError());

      await expect(taskService.createTask({ title: 'Duplicate' }))
        .rejects.toThrow(APIError);
    });
  });
});

Testy integracyjne

# Generuj testy integracji API
"Utwórz testy integracyjne:
- Testowanie rzeczywistych endpointów HTTP
- Integracja z bazą danych
- Przepływ uwierzytelniania
- Odpowiedzi błędów"

describe('Tasks API', () => {
  beforeAll(async () => {
    await setupTestDatabase();
  });

  describe('GET /tasks', () => {
    it('powinien zwrócić spaginowane zadania', async () => {
      const token = await getAuthToken();

      const response = await request(app)
        .get('/api/tasks?page=1&limit=10')
        .set('Authorization', `Bearer ${token}`)
        .expect(200);

      expect(response.body).toMatchObject({
        data: expect.any(Array),
        pagination: {
          page: 1,
          limit: 10,
          total: expect.any(Number)
        }
      });
    });
  });
});

Testy kontraktowe

# Generuj testy kontraktowe
"Utwórz testy Pact dla mikroserwisów:
- Kontrakty sterowane przez konsumenta
- Weryfikacja dostawcy
- Walidacja schematu"

Testowanie obciążenia

# Generuj testy obciążenia k6
"Utwórz scenariusze testów obciążenia:
- Stopniowe zwiększanie obciążenia
- Testowanie skoków
- Testowanie stresu
- Testowanie wytrzymałości"

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 100 },  // Zwiększanie
    { duration: '5m', target: 100 },  // Utrzymanie na 100
    { duration: '2m', target: 200 },  // Skok
    { duration: '5m', target: 200 },  // Utrzymane obciążenie
    { duration: '2m', target: 0 },    // Zmniejszanie
  ],
  thresholds: {
    http_req_duration: ['p(95) < 500'], // 95% żądań poniżej 500ms
    http_req_failed: ['rate < 0.1'],   // Wskaźnik błędów poniżej 10%
  },
};

export default function () {
  const token = getAuthToken();

  const response = http.get('https://api.example.com/tasks', {
    headers: { Authorization: `Bearer ${token}` },
  });

  check(response, {
    'status jest 200': (r) => r.status === 200,
    'czas odpowiedzi < 500ms': (r) => r.timings.duration < 500,
  });

  sleep(1);
}

Dokumentacja API

Interaktywna dokumentacja

# Generuj dokumentację API
"Utwórz kompleksową dokumentację API:
- Interaktywny eksplorer API
- Przykłady kodu w wielu językach
- Przewodnik uwierzytelniania
- Informacje o limitach
- Changelog"

// Konfiguracja Swagger UI
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Task Management API',
      version: '1.0.0',
      description: 'Kompletny system zarządzania zadaniami',
      contact: {
        email: 'api@example.com'
      }
    },
    servers: [
      { url: 'https://api.example.com/v1', description: 'Produkcja' },
      { url: 'https://staging-api.example.com/v1', description: 'Staging' }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT'
        }
      }
    }
  },
  apis: ['./src/routes/*.ts'], // Ścieżka do tras API
};

Generowanie SDK

SDK w wielu językach

# Generuj SDK klientów
"Generuj SDK ze specyfikacji OpenAPI:
- TypeScript/JavaScript
- Python
- Go
- Java
- Dołącz pomocniki uwierzytelniania
- Logikę ponawiania
- Bezpieczeństwo typów"

# Używając OpenAPI Generator
openapi-generator generate -i api.yaml -g typescript-axios -o ./sdk/typescript
openapi-generator generate -i api.yaml -g python -o ./sdk/python
openapi-generator generate -i api.yaml -g go -o ./sdk/go

Wersjonowanie API

Strategia wersjonowania

# Zaimplementuj wersjonowanie API
"Zaprojektuj strategię wersjonowania:
- Wersjonowanie URL (/v1, /v2)
- Wersjonowanie nagłówków
- Ostrożenia o deprecacji
- Przewodniki migracji"

// Wersjonowanie oparte na URL
app.use('/api/v1', v1Routes);
app.use('/api/v2', v2Routes);

// Wersjonowanie oparte na nagłówkach
const versionMiddleware = (req: Request, res: Response, next: NextFunction) => {
  const version = req.headers['api-version'] || 'v1';
  req.apiVersion = version;

  // Dodaj ostrzeżenia o deprecacji
  if (version === 'v1') {
    res.setHeader('X-API-Deprecation', 'Wersja 1 zostanie wycofana 2025-12-31');
    res.setHeader('X-API-Migration', 'https://docs.api.com/migration-v2');
  }

  next();
};

Optymalizacja wydajności

Strategie cachowania

# Zaimplementuj cachowanie
"Dodaj warstwy cachowania:
- Redis dla danych sesji
- CDN dla treści statycznych
- Cachowanie zapytań do bazy danych
- Cachowanie odpowiedzi
- Unieważnianie cache"

// Middleware cachowania Redis
const cache = (duration: number) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    const key = `cache:${req.originalUrl}`;

    try {
      const cached = await redis.get(key);
      if (cached) {
        return res.json(JSON.parse(cached));
      }
    } catch (error) {
      logger.error('Błąd cache:', error);
    }

    // Przechowaj oryginalną metodę json
    const originalJson = res.json;

    // Nadpisz metodę json
    res.json = function(data) {
      // Cachuj odpowiedź
      redis.setex(key, duration, JSON.stringify(data))
        .catch(err => logger.error('Błąd ustawiania cache:', err));

      // Wywołaj oryginalną metodę json
      return originalJson.call(this, data);
    };

    next();
  };
};

// Użycie
router.get('/popular-posts', cache(300), async (req, res) => {
  const posts = await postService.getPopular();
  res.json(posts);
});

Ograniczanie prędkości

# Zaimplementuj ograniczanie prędkości
"Dodaj ograniczanie prędkości:
- Limity per użytkownik
- Poziomy kluczy API
- Limity specyficzne dla endpointów
- Gracefulna degradacja"

const rateLimiter = createRateLimiter({
  windowMs: 15 * 60 * 1000, // 15 minut
  max: (req) => {
    // Różne limity w zależności od poziomu użytkownika
    if (req.user?.tier === 'premium') return 1000;
    if (req.user?.tier === 'basic') return 100;
    return 50; // Użytkownicy anonimowi
  },
  message: 'Zbyt wiele żądań',
  standardHeaders: true,
  legacyHeaders: false,
});

Najlepsze praktyki

Design first
- Zacznij od specyfikacji API
- Uzyskaj zgodę interesariuszy
- Wersjonuj od pierwszego dnia
- Planuj deprecację
Bezpieczeństwo domyślnie
- Uwierzytelniaj wszystkie endpointy
- Waliduj wszystkie dane wejściowe
- Używaj tylko HTTPS
- Zaimplementuj ograniczanie prędkości
Developer experience
- Kompleksowa dokumentacja
- Interaktywny eksplorer API
- SDK w wielu językach
- Jasne komunikaty błędów
Fokus na wydajność
- Zaimplementuj cachowanie
- Używaj paginacji
- Optymalizuj zapytania
- Monitoruj czasy odpowiedzi

Rozwój API z AI transformuje cały cykl życia od projektowania do wdrożenia, umożliwiając zespołom budowanie solidnych, dobrze udokumentowanych API, które skalują się z potrzebami biznesowymi przy zachowaniu wysokich standardów jakości.