К основному содержанию
скилл CX Codex

api-contract-review — скилл для Claude Code: проверка REST API

Скилл api-contract-review для Claude Code проверяет REST API-контракты на ошибки HTTP-семантики, версионирования и совместимости. Запускается по просьбе проверить API или перед выпуском изменений.

MIT 329 установок ★ 778 обновлён 2026-09-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add decebals/claude-code-java --skill api-contract-review -a claude-code
Открыть на GitHub

Что делает api-contract-review

api-contract-review разбирает REST-эндпоинты и проверяет, подходят ли им HTTP-методы и коды ответа. Он ищет несогласованные форматы ответов, нарушения обратной совместимости и утечки внутренних сущностей вместо DTO. Скилл также проверяет пагинацию коллекций и структуру ошибок.

Проверка охватывает версионирование API и единообразие имён маршрутов. Для публичных API скилл рекомендует версию в пути, например /v1/users. Его можно подключить при ревью PR с изменениями контроллеров.

Какие задачи решает

  • найти неверный HTTP-метод для операции
  • проверить обратную совместимость изменений API
  • обнаружить непоследовательные коды и форматы ответов
  • выявить выдачу сущностей вместо DTO

Примеры запросов агенту

  • Проверь REST API и найди ошибки в HTTP-методах и кодах ответа.
  • Проведи ревью контроллеров в этом PR перед выпуском изменений.
  • Проверь версионирование и обратную совместимость эндпоинтов.

Как установить api-contract-review

1Через Skills CLI (Vercel)

npx skills add decebals/claude-code-java --skill api-contract-review -a claude-code

2Вручную: положить файлы

~/.claude/skills/api-contract-review/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/api-contract-review/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об api-contract-review

Как установить api-contract-review в Claude Code?

Выполни npx skills add decebals/claude-code-java --skill api-contract-review -a claude-code. Файл скилла находится по пути ~/.claude/skills/api-contract-review/SKILL.md.

Что делает api-contract-review?

Скилл проверяет REST-контракты: HTTP-методы и статусы, версионирование, совместимость, форматы ответов и пагинацию.

Как api-contract-review проверяет версионирование API?

Он ищет версию в маршрутах публичных API и рекомендует указывать её в пути, например /v1/users.

Исходный текст

SKILL.md · MIT
---
name: api-contract-review
description: Review REST API contracts for HTTP semantics, versioning, backward compatibility, and response consistency. Use when user asks "review API", "check endpoints", "REST review", or before releasing API changes.
license: MIT
---

# API Contract Review Skill

Audit REST API design for correctness, consistency, and compatibility.

## When to Use
- User asks "review this API" / "check REST endpoints"
- Before releasing API changes
- Reviewing PR with controller changes
- Checking backward compatibility

---

## Quick Reference: Common Issues

| Issue | Symptom | Impact |
|-------|---------|--------|
| Wrong HTTP verb | POST for idempotent operation | Confusion, caching issues |
| Missing versioning | `/users` instead of `/v1/users` | Breaking changes affect all clients |
| Entity leak | JPA entity in response | Exposes internals, N+1 risk |
| 200 with error | `{"status": 200, "error": "..."}` | Breaks error handling |
| Inconsistent naming | `/getUsers` vs `/users` | Hard to learn API |

---

## HTTP Verb Semantics

### Verb Selection Guide

| Verb | Use For | Idempotent | Safe | Request Body |
|------|---------|------------|------|--------------|
| GET | Retrieve resource | Yes | Yes | No |
| POST | Create new resource | No | No | Yes |
| PUT | Replace entire resource | Yes | No | Yes |
| PATCH | Partial update | No* | No | Yes |
| DELETE | Remove resource | Yes | No | Optional |

*PATCH can be idempotent depending on implementation

### Common Mistakes

```java
// ❌ POST for retrieval
@PostMapping("/users/search")
public List<User> searchUsers(@RequestBody SearchCriteria criteria) { }

// ✅ GET with query params (or POST only if criteria is very complex)
@GetMapping("/users")
public List<User> searchUsers(
    @RequestParam String name,
    @RequestParam(required = false) String email) { }

// ❌ GET for state change
@GetMapping("/users/{id}/activate")
public void activateUser(@PathVariable Long id) { }

// ✅ POST or PATCH for state change
@PostMapping("/users/{id}/activate")
public ResponseEntity<Void> activateUser(@PathVariable Long id) { }

// ❌ POST for idempotent update
@PostMapping("/users/{id}")
public User updateUser(@PathVariable Long id, @RequestBody UserDto dto) { }

// ✅ PUT for full replacement, PATCH for partial
@PutMapping("/users/{id}")
public User replaceUser(@PathVariable Long id, @RequestBody UserDto dto) { }

@PatchMapping("/users/{id}")
public User updateUser(@PathVariable Long id, @RequestBody UserPatchDto dto) { }
```

---

## API Versioning

### Strategies

| Strategy | Example | Pros | Cons |
|----------|---------|------|------|
| URL path | `/v1/users` | Clear, easy routing | URL changes |
| Header | `Accept: application/vnd.api.v1+json` | Clean URLs | Hidden, harder to test |
| Query param | `/users?version=1` | Easy to add | Easy to forget |

### Recommended: URL Path

```java
// ✅ Versioned endpoints
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 { }

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 { }

// ❌ No versioning
@RestController
@RequestMapping("/api/users")  // Breaking changes affect everyone
public class UserController { }
```

### Version Checklist
- [ ] All public APIs have version in path
- [ ] Internal APIs documented as internal (or versioned too)
- [ ] Deprecation strategy defined for old versions

---

## Request/Response Design

### DTO vs Entity

```java
// ❌ Entity in response (leaks internals)
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
    return userRepository.findById(id).orElseThrow();
    // Exposes: password hash, internal IDs, lazy collections
}

// ✅ DTO response
@GetMapping("/{id}")
public UserResponse getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    return UserResponse.from(user);  // Only public fields
}
```

### Response Consistency

```java
// ❌ Inconsistent responses
@GetMapping("/users")
public List<User> getUsers() { }  // Returns array

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) { }  // Returns object

@GetMapping("/users/count")
public int countUsers() { }  // Returns primitive

// ✅ Consistent wrapper (optional but recommended for large APIs)
@GetMapping("/users")
public ApiResponse<List<UserResponse>> getUsers() {
    return ApiResponse.success(userService.findAll());
}

// Or at minimum, consistent structure:
// - Collections: always wrapped or always raw (pick one)
// - Single items: always object
// - Counts/stats: always object { "count": 42 }
```

### Pagination

```java
// ❌ No pagination on collections
@GetMapping("/users")
public List<User> getAllUsers() {
    return userRepository.findAll();  // Could be millions
}

// ✅ Paginated
@GetMapping("/users")
public Page<UserResponse> getUsers(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "20") int size) {
    return userService.findAll(PageRequest.of(page, size));
}
```

---

## HTTP Status Codes

### Success Codes

| Code | When to Use | Response Body |
|------|-------------|---------------|
| 200 OK | Successful GET, PUT, PATCH | Resource or result |
| 201 Created | Successful POST (created) | Created resource + Location header |
| 204 No Content | Successful DELETE, or PUT with no body | Empty |

### Error Codes

| Code | When to Use | Common Mistake |
|------|-------------|----------------|
| 400 Bad Request | Invalid input, validation failed | Using for "not found" |
| 401 Unauthorized | Not authenticated | Confusing with 403 |
| 403 Forbidden | Authenticated but not allowed | Using 401 instead |
| 404 Not Found | Resource doesn't exist | Using 400 |
| 409 Conflict | Duplicate, concurrent modification | Using 400 |
| 422 Unprocessable | Semantic error (valid syntax, invalid meaning) | Using 400 |
| 500 Internal Error | Unexpected server error | Exposing stack traces |

### Anti-Pattern: 200 with Error Body

```java
// ❌ NEVER DO THIS
@GetMapping("/{id}")
public ResponseEntity<Map<String, Object>> getUser(@PathVariable Long id) {
    try {
        User user = userService.findById(id);
        return ResponseEntity.ok(Map.of("status", "success", "data", user));
    } catch (NotFoundException e) {
        return ResponseEntity.ok(Map.of(  // Still 200!
            "status", "error",
            "message", "User not found"
        ));
    }
}

// ✅ Use proper status codes
@GetMapping("/{id}")
public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
    return userService.findById(id)
        .map(ResponseEntity::ok)
        .orElse(ResponseEntity.notFound().build());
}
```

---

## Error Response Format

### Consistent Error Structure

```java
// ✅ Standard error response
public class ErrorResponse {
    private String code;        // Machine-readable: "USER_NOT_FOUND"
    private String message;     // Human-readable: "User with ID 123 not found"
    private Instant timestamp;
    private String path;
    private List<FieldError> errors;  // For validation errors
}

// In GlobalExceptionHandler
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(
        ResourceNotFoundException ex, HttpServletRequest request) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND)
        .body(ErrorResponse.builder()
            .code("RESOURCE_NOT_FOUND")
            .message(ex.getMessage())
            .timestamp(Instant.now())
            .path(request.getRequestURI())
            .build());
}
```

### Security: Don't Expose Internals

```java
// ❌ Exposes stack trace
@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleAll(Exception ex) {
    return ResponseEntity.status(500)
        .body(ex.getStackTrace().toString());  // Security risk!
}

// ✅ Generic message, log details server-side
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAll(Exception ex) {
    log.error("Unexpected error", ex);  // Full details in logs
    return ResponseEntity.status(500)
        .body(ErrorResponse.of("INTERNAL_ERROR", "An unexpected error occurred"));
}
```

---

## Backward Compatibility

### Breaking Changes (Avoid in Same Version)

| Change | Breaking? | Migration |
|--------|-----------|-----------|
| Remove endpoint | Yes | Deprecate first, remove in next version |
| Remove field from response | Yes | Keep field, return null/default |
| Add required field to request | Yes | Make optional with default |
| Change field type | Yes | Add new field, deprecate old |
| Rename field | Yes | Support both temporarily |
| Change URL path | Yes | Redirect old to new |

### Non-Breaking Changes (Safe)

- Add optional field to request
- Add field to response
- Add new endpoint
- Add new optional query parameter

### Deprecation Pattern

```java
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {

    @Deprecated
    @GetMapping("/by-email")  // Old endpoint
    public UserResponse getByEmailOld(@RequestParam String email) {
        return getByEmail(email);  // Delegate to new
    }

    @GetMapping(params = "email")  // New pattern
    public UserResponse getByEmail(@RequestParam String email) {
        return userService.findByEmail(email);
    }
}
```

---

## API Review Checklist

### 1. HTTP Semantics
- [ ] GET for retrieval only (no side effects)
- [ ] POST for creation (returns 201 + Location)
- [ ] PUT for full replacement (idempotent)
- [ ] PATCH for partial updates
- [ ] DELETE for removal (idempotent)

### 2. URL Design
- [ ] Versioned (`/v1/`, `/v2/`)
- [ ] Nouns, not verbs (`/users`, not `/getUsers`)
- [ ] Plural for collections (`/users`, not `/user`)
- [ ] Hierarchical for relationships (`/users/{id}/orders`)
- [ ] Consistent naming (kebab-case or camelCase, pick one)

### 3. Request Handling
- [ ] Validation with `@Valid`
- [ ] Clear error messages for validation failures
- [ ] Request DTOs (not entities)
- [ ] Reasonable size limits

### 4. Response Design
- [ ] Response DTOs (not entities)
- [ ] Consistent structure across endpoints
- [ ] Pagination for collections
- [ ] Proper status codes (not 200 for errors)

### 5. Error Handling
- [ ] Consistent error format
- [ ] Machine-readable error codes
- [ ] Human-readable messages
- [ ] No stack traces exposed
- [ ] Proper 4xx vs 5xx distinction

### 6. Compatibility
- [ ] No breaking changes in current version
- [ ] Deprecated endpoints documented
- [ ] Migration path for breaking changes

---

## Token Optimization

For large APIs:
1. List all controllers: `find . -name "*Controller.java"`
2. Sample 2-3 controllers for pattern analysis
3. Check `@ExceptionHandler` configuration once
4. Grep for specific anti-patterns:
   ```bash
   # Find potential entity leaks
   grep -r "public.*Entity.*@GetMapping" --include="*.java"

   # Find 200 with error patterns
   grep -r "ResponseEntity.ok.*error" --include="*.java"

   # Find unversioned APIs
   grep -r "@RequestMapping.*api" --include="*.java" | grep -v "/v[0-9]"
   ```

© decebals · MIT · decebals/claude-code-java

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
rest-api-design-patterns manutej Скилл rest-api-design-patterns для Claude Code помогает проектировать и приводить к единому виду REST API: моделировать ресурсы, версионирование, пагинацию, HATEOAS и HTTP-методы. CX Codex +1 527установок public-api-design-review Samuel Berthe Скилл public-api-design-review проводит REST API, готовый или ещё на бумаге, по чек-листу из восьми разделов и делит находки на обязательные правки и улучшения. CX Codex +1 10 200установок api-contract-normalizer patricio0312rev Скилл api-contract-normalizer для Claude Code приводит ответы API к общим правилам формата, ошибок, пагинации и версий. Унифицирует ответы разных эндпоинтов. CX Codex +1 260установок API Design taste f Промпт API Design taste задаёт правила проектирования REST API с оценками уверенности. Помогает проверять эндпоинты, форматы ошибок и схемы валидации. GP ChatGPT ★ 178 201звёзд репо api-versioning-strategy secondsky Скилл api-versioning-strategy помогает выбрать способ версионирования API и провести старую версию до отключения без сюрпризов для клиентов. CX Codex +1 417установок rest-api-design secondsky Скилл rest-api-design для Claude Code и других агентов задаёт конвенции REST: имена ресурсов, HTTP-методы, коды ответов и формат JSON. Покрывает проектирование нового API и ревью существующего. CX Codex +1 607установок

Из того же набора18

Весь набор →
java-migration Скилл java-migration для Claude Code ведёт проект по цепочке LTS-версий Java: от оценки текущего состояния до правки сборки и тестов. Переводит легаси на Java 21 или 25. CX Codex +1 372установок security-audit Скилл security-audit для Claude Code сверяет Java-код с чек-листом OWASP Top 10: проверяет валидацию ввода, SQL-инъекции, XSS и настройки безопасности. Включается перед релизом и при ревью авторизации. CX Codex +1 364установок performance-smell-detection Скилл performance-smell-detection находит узкие места в Java-коде: создание лишних объектов и компиляцию regex в циклах. Помогает при ревью критичных к нагрузке участков. CX Codex +1 361установок test-quality Скилл test-quality пишет качественные unit-тесты на Java с JUnit 5 и AssertJ. Включите его, когда нужно добавить тесты к коду или улучшить покрытие. CX Codex +1 356установок maven-dependency-audit Скилл maven-dependency-audit проверяет Maven-зависимости на устаревшие версии, конфликты и известные уязвимости. Пригодится перед релизом или после выхода security-бюллетеня. CX Codex +1 322установок jpa-patterns Скилл jpa-patterns обучает ИИ-агента находить проблему N+1 в Spring-проектах, чинить LazyInitializationException и настраивать выборки в JPA и Hibernate. CX Codex +1 313установок logging-patterns Скилл logging-patterns для Claude Code задаёт правила логирования Java через SLF4J, JSON и MDC. Разбирает поток запросов и помогает отлаживать по логам. CX Codex +1 313установок changelog-generator Скилл changelog-generator собирает changelog из conventional commits и помогает подготовить запись к релизу. Подходит для Java-проектов с git-историей. CX Codex +1 265установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой