스웨거 펫스토어 예제가 REST API 디자인에 나쁜 이유?

요약

Swagger Petstore는 근본적인 REST 원칙을 위반합니다: 일관성 없는 단수 리소스 이름을 사용하고, URL에 액션 동사를 포함하며, 잘못된 HTTP 상태 코드를 반환하고, GET 요청에서 비밀번호를 노출하며, 메타데이터 없이 순수 배열을 반환합니다. Modern PetstoreAPI는 적절한 RESTful 디자인, RFC 9457 오류 처리, 그리고 프로덕션 준비된 패턴으로 이 모든 문제를 해결합니다.

서론

10년이 넘는 시간 동안 Swagger Petstore는 OpenAPI 학습의 기본 예시였습니다. 수백만 명의 개발자들이 이를 연구하고 패턴을 복사하며, 이 디자인을 기반으로 프로덕션 API를 구축했습니다. 여기에는 한 가지 문제가 있습니다: 나쁜 API를 구축하도록 가르친다는 것입니다.

Swagger Petstore는 기본적인 REST 원칙을 위반하고, 보안 취약점을 포함하며, 프로덕션 시스템에 해를 끼치는 안티패턴을 보여줍니다. 이는 브레이크와 가속 페달이 뒤바뀐 차로 운전을 배우는 것과 같습니다—배우긴 하겠지만, 잘못 배우게 될 것입니다.

피해는 실제적입니다. Swagger Petstore에서 배운 개발자들은 이러한 안티패턴을 프로덕션 코드에 적용합니다. API는 일관성 없는 명명, 잘못된 HTTP 메서드, 그리고 보안 취약점을 가지고 구축됩니다. 코드 리뷰에서 이러한 문제들이 간과되는데, 그 이유는 “Petstore가 그렇게 하니까요.” 라는 생각 때문입니다.

💡

REST API를 구축하거나 테스트 중이라면, Apidog는 REST 원칙에 대한 API 디자인을 검증하고, 엔드포인트 동작을 테스트하며, 프로덕션에 도달하기 전에 디자인 결함을 잡아내는 데 도움을 줍니다. OpenAPI 스펙을 가져오고, 자동화된 테스트를 실행하며, API가 적절한 REST 규칙을 따르는지 확인할 수 있습니다.

버튼

이 가이드에서는 Swagger Petstore의 정확히 무엇이 잘못되었는지, 이러한 문제들이 왜 중요한지, 그리고 Modern PetstoreAPI가 프로덕션 준비된 패턴으로 이 문제들을 어떻게 해결하는지 배우게 될 것입니다. 나란히 비교하여 각 위반 사항의 영향을 이해하고, Apidog로 API를 올바르게 테스트하는 방법을 발견할 수 있을 것입니다.

Swagger Petstore의 레거시 문제

Swagger Petstore는 2011년에 Swagger 명세(현재 OpenAPI)의 간단한 예시로 생성되었습니다. 그것은 OpenAPI 스펙을 작성하는 방법을 시연하는 목적을 달성했습니다. 하지만 REST API 디자인을 위한 참고 자료로 의도된 것은 아니었습니다.

왜 사실상 표준이 되었는가

개발자들이 OpenAPI를 배울 때, 공식 예시로 시작합니다. Swagger Petstore가 바로 그 예시입니다. 문서, 튜토리얼, 코드 생성기에 등장합니다. Swagger UI나 Swagger Codegen을 사용해봤다면, 이를 보셨을 겁니다.

문제는 개발자들이 “공식 예시 = 모범 사례”라고 가정한다는 것입니다. 그들은 의심 없이 패턴을 복사합니다. API 디자인 강좌는 이를 교육 도구로 사용합니다. 회사들은 그 구조를 따라 내부 API를 구축합니다.

나쁜 예시의 대가

나쁜 예시는 시간이 지남에 따라 누적됩니다:

주니어 개발자들이 안티패턴을 배웁니다 - 이들이 실수인 줄 모릅니다
코드 생성기가 문제를 영속화합니다 - 생성된 SDK는 결함을 상속받습니다
문서화 도구가 나쁜 예시를 보여줍니다 - Swagger UI는 기본적으로 Petstore를 표시합니다
회사들이 이러한 방식으로 프로덕션 API를 구축합니다 - “Swagger에 충분하다면…”

Swagger Petstore는 역사상 그 어떤 예시보다 더 많은 API 디자인에 영향을 미쳤을 것입니다. 이것이 바로 그 결함이 중요한 이유입니다.

Swagger Petstore의 치명적인 REST 위반 사항

Swagger Petstore의 구체적인 REST 위반 사항과 그것들이 왜 잘못되었는지 살펴보겠습니다.

1. 일관성 없는 리소스 이름 지정 (복수 vs 단수)

위반 사항:

GET /pet/{petId}           ← Singular
GET /store/inventory       ← Plural
POST /pet                  ← Singular
GET /user/{username}       ← Singular

왜 잘못되었는가:

REST 리소스는 컬렉션을 나타냅니다. 컬렉션은 복수형입니다. /pets에 접근할 때, 당신은 펫 컬렉션에 접근하는 것입니다. /pets/123에 접근할 때, 당신은 펫 컬렉션의 123번 항목에 접근하는 것입니다.

단수와 복수를 혼용하는 것은 이 멘탈 모델을 깨뜨립니다. /pet/123이 펫 컬렉션에 접근하는 것인가, 아니면 단일 펫 리소스에 접근하는 것인가? 이러한 불일치는 혼란을 야기합니다.

Modern PetstoreAPI 수정 사항:

GET /pets/{petId}          ← Always plural
GET /stores/inventory      ← Consistent
POST /pets                 ← Plural for collection
GET /users/{username}      ← Plural everywhere

Modern PetstoreAPI는 모든 엔드포인트에서 일관되게 복수형 리소스 이름을 사용합니다. 완전한 엔드포인트 구조는 REST API 문서에서 확인하세요.

2. URL에 액션 동사 사용

위반 사항:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

왜 잘못되었는가:

REST URL은 액션(동사)이 아닌 리소스(명사)를 나타내야 합니다. HTTP 메서드가 동사입니다. GET /pets는 “펫 리소스를 가져오라”는 의미입니다. findByStatus를 추가하는 것은 불필요합니다—이는 쿼리 파라미터가 담당하는 역할입니다.

URL에 액션 동사를 사용하는 것은 REST 용어가 아닌 RPC(원격 프로시저 호출) 방식으로 생각하고 있음을 나타냅니다. 리소스 대신 구현 세부 사항을 노출하는 것입니다.

Modern PetstoreAPI 수정 사항:

GET /pets?status=AVAILABLE              ← Resource + filter
GET /pets?tags=tag1,tag2                ← Query parameters for filtering
POST /auth/login                        ← Separate auth resource
POST /auth/logout                       ← RESTful auth endpoints

Modern PetstoreAPI는 필터링을 위해 쿼리 파라미터를 사용하고 별도의 인증 리소스를 사용합니다. 적절한 인증 패턴에 대해서는 인증 가이드를 참조하세요.

3. 잘못된 HTTP 상태 코드

위반 사항:

POST /pet
Response: 200 OK          ← Should be 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← Should be 204 No Content
{
  "message": "Pet deleted"
}

왜 잘못되었는가:

HTTP 상태 코드는 특정 의미를 가집니다:

200 OK는 “요청 성공, 여기 리소스가 있습니다”를 의미합니다.
201 Created는 “리소스 생성됨, 여기에서 찾을 수 있습니다”를 의미합니다.
204 No Content는 “요청 성공, 반환할 본문 없음”을 의미합니다.

모든 것에 200을 사용하는 것은 HTTP 의미론을 위반합니다. 클라이언트는 “리소스 검색됨”과 “리소스 생성됨”을 구별할 수 없습니다. DELETE 요청에 본문을 반환하는 것은 대역폭 낭비입니다—클라이언트는 확인 텍스트가 필요하지 않습니다.

Modern PetstoreAPI 수정 사항:

POST /pets
Response: 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Response: 204 No Content
(no body)

Modern PetstoreAPI는 올바른 HTTP 상태 코드를 사용하며, 생성된 리소스에 대해 Location 헤더를 포함합니다. 전체 매핑은 HTTP 상태 코드 가이드를 참조하세요.

4. 메타데이터 없는 순수 배열

위반 사항:

GET /pet/findByStatus?status=available
Response: 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

왜 잘못되었는가:

순수 배열을 반환하는 것은 문제를 야기합니다:

페이지네이션 메타데이터 없음 - 총 항목 수는? 현재 몇 페이지인가?
확장성 없음 - 클라이언트를 깨뜨리지 않고 메타데이터를 추가할 수 없음
HATEOAS 링크 없음 - 내비게이션 링크를 포함할 수 없음
JSON 하이재킹 위험 - 순수 배열은 특정 공격에 취약함

Modern PetstoreAPI 수정 사항:

GET /pets?status=AVAILABLE
Response: 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

Modern PetstoreAPI는 모든 컬렉션을 메타데이터와 HATEOAS 링크가 포함된 객체로 감쌉니다. 구현 세부 사항은 페이지네이션 가이드를 참조하세요.

5. 누락된 오류 표준

위반 사항:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

왜 잘못되었는가:

이 오류 형식은 비표준적이며 최소한의 정보만 제공합니다:

오류 유형 식별자 없음
필드 수준 유효성 검사 오류 없음
기계 판독 가능한 오류 코드 없음
RFC 9457 (문제 상세)를 따르지 않음

Modern PetstoreAPI 수정 사항:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

Modern PetstoreAPI는 모든 오류에 대해 RFC 9457 문제 상세를 사용합니다. 완전한 오류 형식은 오류 처리 가이드를 참조하세요.

오래된 디자인의 보안 재앙

REST 위반 사항 외에도 Swagger Petstore는 심각한 보안 문제를 가지고 있습니다.

비밀번호를 포함한 GET 요청

위반 사항:

GET /user/login?username=john&password=secret123

왜 재앙인가:

GET 요청의 비밀번호는 다음 위치에 나타납니다:

브라우저 기록 - 브라우저에 접근할 수 있는 모든 사람이 비밀번호를 볼 수 있습니다
서버 로그 - 웹 서버는 쿼리 파라미터를 포함한 전체 URL을 로깅합니다
리퍼러 헤더 - 사용자가 로그인 후 링크를 클릭하면, 다음 사이트가 비밀번호를 봅니다
프록시 로그 - 기업 프록시는 모든 URL을 로깅합니다
브라우저 북마크 - 사용자가 로그인 URL을 북마크할 수 있습니다

이것은 치명적인 보안 취약점입니다. 비밀번호는 절대로 URL에 포함되어서는 안 됩니다.

Modern PetstoreAPI 수정 사항:

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

Modern PetstoreAPI는 JSON 본문을 사용하여 인증에 POST를 사용합니다. 비밀번호는 절대로 URL에 나타나지 않습니다. OAuth 2.0 및 JWT 패턴에 대해서는 인증 가이드를 참조하세요.

쿼리 파라미터의 API 키

위반 사항:

GET /pet/123?api_key=abc123secret

왜 잘못되었는가:

쿼리 파라미터의 API 키는 URL의 비밀번호와 동일한 문제를 가집니다:

모든 곳에 로깅됨
브라우저 기록에 노출됨
리퍼러 헤더로 전송됨
프록시에 의해 캐시됨

Modern PetstoreAPI 수정 사항:

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Modern PetstoreAPI는 API 키 및 토큰에 표준 Authorization 헤더를 사용합니다. 인증 패턴에 대해서는 보안 가이드를 참조하세요.

Modern PetstoreAPI가 이러한 문제를 해결하는 방법

Modern PetstoreAPI는 적절한 REST API 디자인을 시연하기 위해 처음부터 구축되었습니다. 다음은 차별점입니다:

프로덕션 준비된 REST 디자인

일관된 복수 리소스 이름 - /pets, /orders, /users
리소스 지향 URL - 액션 동사 없이 명사만 사용
올바른 HTTP 상태 코드 - 생성에 201, 삭제에 204, 적절한 오류 코드
컬렉션 래퍼 - 모든 목록에 페이지네이션 및 메타데이터 포함
RFC 9457 오류 - 필드 수준 유효성 검사가 포함된 표준 오류 형식

현대 표준

OpenAPI 3.2 - 모든 기능을 포함한 최신 명세
RFC 9457 - HTTP API용 문제 상세
IETF Rate Limiting - 표준 RateLimit-* 헤더
ISO 8601 - 적절한 날짜/시간 형식
UUIDv7 - 정렬 가능한 고유 식별자

다중 프로토콜 지원

Swagger Petstore(REST 전용)와 달리, Modern PetstoreAPI는 다음을 지원합니다:

REST (OpenAPI 3.2)
GraphQL
gRPC
WebSocket
Server-Sent Events (SSE)
MQTT
Webhooks
Model Context Protocol (MCP)

구현 세부 사항은 프로토콜 가이드를 참조하세요.

실제 비즈니스 로직

Modern PetstoreAPI는 현실적인 기능을 포함합니다:

결제 처리
재고 관리
주문 처리
웹훅 알림
AI 기반 반려동물 추천
이미지 업로드 및 처리

전체 기능 세트는 API 문서에서 확인하세요.

Apidog로 REST API 디자인 테스트하기

Apidog는 REST API 디자인을 검증하고 프로덕션에 도달하기 전에 위반 사항을 잡아내는 데 도움을 줍니다.

OpenAPI 스펙 가져오기 및 검증하기

# Modern PetstoreAPI 스펙 가져오기
1. Apidog 열기
2. "가져오기" → "OpenAPI" 클릭
3. 다음 주소 입력: https://petstoreapi.com/openapi.json
4. Apidog가 스펙을 검증하고 테스트 케이스를 생성합니다

Apidog는 자동으로 다음을 감지합니다:

일관성 없는 리소스 이름 지정
누락된 HTTP 상태 코드
잘못된 응답 구조
인증의 보안 문제

REST 원칙 테스트

REST 규정 준수를 확인하는 테스트 케이스를 생성하세요:

테스트: 리소스 이름은 복수형입니다

// Apidog 테스트 스크립트
pm.test("엔드포인트가 복수 리소스 이름을 사용합니다", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

테스트: 올바른 상태 코드

pm.test("POST는 201 Created를 반환합니다", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE는 204 No Content를 반환합니다", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

테스트: 컬렉션에 메타데이터가 있습니다

pm.test("컬렉션 응답에 페이지네이션이 포함됩니다", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

구 Petstore vs 신 Petstore 비교

두 스펙을 Apidog로 가져와서 나란히 비교 실행하세요:

Swagger Petstore 가져오기: https://petstore.swagger.io/v2/swagger.json
Modern PetstoreAPI 가져오기: https://petstoreapi.com/openapi.json
둘 다에 대해 자동화된 테스트 실행
결과를 비교하여 차이점 확인

Apidog는 Swagger Petstore의 디자인 위반 사항을 강조하고 Modern PetstoreAPI가 이를 어떻게 수정하는지 보여줄 것입니다.

마이그레이션 가이드: 구 Petstore에서 현대적인 디자인으로

Swagger Petstore를 기반으로 API를 구축했다면, 적절한 REST 디자인으로 마이그레이션하는 방법은 다음과 같습니다:

1단계: 리소스 이름 수정

이전:

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

이후:

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

마이그레이션 전략:

전환 기간 동안 두 엔드포인트를 모두 지원합니다
이전 엔드포인트에 사용 중단 경고를 추가합니다
새로운 엔드포인트를 보여주도록 문서를 업데이트합니다
사용량을 모니터링하고 6개월 후 이전 엔드포인트를 제거합니다

2단계: 액션 동사 제거

이전:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

이후:

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

마이그레이션 전략:

301 Moved Permanently로 이전 엔드포인트를 새로운 엔드포인트로 리디렉션합니다
새로운 엔드포인트를 사용하도록 클라이언트 SDK를 업데이트합니다
쿼리 파라미터 유효성 검사를 추가합니다

3단계: HTTP 상태 코드 수정

이전:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK with body

이후:

POST /pets → 201 Created with Location header
DELETE /pets/{petId} → 204 No Content (no body)

마이그레이션 전략:

이것은 상태 코드를 확인하는 클라이언트에게는 파괴적인 변경입니다
올바른 상태 코드를 사용하여 API 버전을 지정합니다 (v2)
변경 사항을 명확하게 문서화합니다
마이그레이션 일정을 제공합니다

4단계: 컬렉션 래핑

이전:

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

이후:

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

마이그레이션 전략:

이것은 파괴적인 변경입니다
래핑된 응답으로 v2 엔드포인트를 생성합니다
v1 엔드포인트를 사용 중단합니다
새로운 구조를 처리하도록 클라이언트 코드를 업데이트합니다

5단계: RFC 9457 오류 구현

이전:

{
  "code": 400,
  "message": "Invalid input"
}

이후:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

마이그레이션 전략:

Content-Type: application/problem+json 헤더를 추가합니다
전환 기간 동안 이전 및 새로운 오류 형식을 모두 포함합니다
클라이언트 오류 처리를 업데이트합니다
마이그레이션 기간 후 이전 형식을 제거합니다

나쁜 API 디자인의 실제 영향

나쁜 API 디자인은 실제 비용을 발생시킵니다:

개발자 혼란

API가 REST 원칙을 위반할 때, 개발자들은 시간을 낭비합니다:

어떤 HTTP 메서드를 사용할지 추측합니다
일관성 없는 명명 패턴을 파악합니다
예상치 못한 상태 코드를 디버깅합니다
적절한 구조 없이 오류를 처리합니다

비용: 통합당 수 시간의 개발자 시간

클라이언트 버그

일관성 없는 API는 클라이언트 측 버그로 이어집니다:

예상치 못한 응답 구조로 인한 파싱 오류
잘못된 HTTP 메서드로 인한 인증 실패
누락된 메타데이터로 인한 페이지네이션 문제
비표준 형식으로 인한 오류 처리 실패

비용: 프로덕션 사고 및 고객 영향

보안 취약점

디자인 결함은 보안 위험을 초래합니다:

URL의 비밀번호가 로깅됩니다
쿼리 파라미터의 API 키가 캐시됩니다
민감한 엔드포인트에 대한 인증 누락
부적절한 오류 메시지로 인한 시스템 정보 유출

비용: 데이터 유출 및 규정 위반

기술 부채

나쁜 예시는 시간이 지남에 따라 누적됩니다:

새로운 개발자들이 안티패턴을 배웁니다
코드 생성기가 결함 있는 SDK를 생성합니다
문서가 잘못된 예시를 보여줍니다
회사들이 동일한 실수로 새로운 API를 구축합니다

비용: 장기적인 유지보수 부담

결론

Swagger Petstore는 간단한 OpenAPI 예시로서의 역할을 다했지만, 이제는 나아갈 때입니다. 그것의 REST 위반, 보안 문제, 그리고 안티패턴은 너무 많은 프로덕션 API에 영향을 미쳤습니다.

Modern PetstoreAPI는 산업이 필요로 하는 참조 구현을 제공합니다: 적절한 REST 디자인, 현대 표준, 다중 프로토콜 지원, 그리고 프로덕션 준비된 패턴. API 디자인 학습 자료 및 참조 자료로 활용하세요.

Apidog로 API를 테스트하여 디자인 위반 사항을 조기에 파악하세요. OpenAPI 스펙을 가져오고, 자동화된 테스트를 실행하며, API가 프로덕션에 배포되기 전에 REST 원칙을 따르는지 확인하세요.

다음 단계:

Modern PetstoreAPI 문서 탐색
자신의 API 디자인을 Modern PetstoreAPI 패턴과 비교
유효성 검사를 위해 자신의 OpenAPI 스펙을 Apidog로 가져오기
위 마이그레이션 가이드를 사용하여 REST 위반 사항 수정
오류 처리를 위해 RFC 9457 채택

나쁜 API 예시의 시대는 끝났습니다. Modern PetstoreAPI로 올바른 방식으로 API를 구축하세요.

자주 묻는 질문

Swagger는 왜 나쁜 예시를 만들었나요?

Swagger Petstore는 2011년에 Swagger 명세의 간단한 시연 목적으로 생성되었습니다. 이는 REST API 디자인 참조 자료로 의도된 것이 아니었습니다. 문제는 그것이 사실상의 표준 예시가 되었고, 그 결함이 수백만 명의 개발자에 의해 복사되었다는 것입니다.

Swagger Petstore 사용을 중단해야 하나요?

네, REST API 디자인 학습을 위해서는 그렇습니다. 대신 Modern PetstoreAPI를 사용하세요. 이는 적절한 REST 원칙, 현대 표준, 프로덕션 준비된 패턴을 보여줍니다. 구 Petstore는 프로덕션 시스템에 해를 끼치는 안티패턴을 가르칩니다.

Modern PetstoreAPI는 프로덕션 준비가 되었나요?

네. Modern PetstoreAPI는 현실적인 비즈니스 로직, 적절한 오류 처리, 인증, 속도 제한, 그리고 보안 기능을 포함합니다. 최소한의 수정으로 배포하거나 자신만의 API 디자인을 위한 참조 자료로 사용할 수 있습니다.

내 API가 REST 원칙을 따르는지 어떻게 테스트하나요?

OpenAPI 스펙을 Apidog로 가져와서 자동화된 테스트를 실행하세요. Apidog는 리소스 이름 지정, HTTP 상태 코드, 응답 구조 및 보안 패턴을 검증합니다. 또한 Modern PetstoreAPI와 API를 나란히 비교할 수도 있습니다.

Swagger Petstore의 가장 큰 실수는 무엇인가요?

쿼리 파라미터에 비밀번호를 포함한 GET /user/login을 사용하는 것입니다. 이는 브라우저 기록, 서버 로그, 리퍼러 헤더에 비밀번호를 노출시켜 치명적인 보안 취약점을 만듭니다. 인증에는 항상 JSON 본문과 함께 POST를 사용하세요.

Swagger Petstore 패턴에서 점진적으로 마이그레이션할 수 있나요?

네. 전환 기간 동안 이전 및 새로운 엔드포인트를 모두 지원하세요. 이전 엔드포인트에 사용 중단 경고를 추가하고, 문서를 업데이트하며, 사용량을 모니터링하세요. 클라이언트가 마이그레이션한 후 (일반적으로 6-12개월 후) 이전 엔드포인트를 제거하세요.

Modern PetstoreAPI는 GraphQL과 gRPC를 지원하나요?

네. Swagger Petstore(REST 전용)와 달리, Modern PetstoreAPI는 REST, GraphQL, gRPC, WebSocket, SSE, MQTT, 웹훅, MCP 등 여러 프로토콜을 지원합니다. 자세한 내용은 프로토콜 가이드를 참조하세요.

우리 팀에게 API 디자인을 수정하도록 어떻게 설득할 수 있나요?

개발자 혼란, 클라이언트 버그, 보안 취약점, 기술 부채와 같은 실제 비용을 보여주세요. Apidog를 사용하여 현재 API의 위반 사항을 시연하세요. 자신의 디자인을 Modern PetstoreAPI와 비교하고 개선 사항을 보여주세요.