기술과 집행 구분
도구가 지원하는 명세 버전을 고정하고 매개변수, 본문, 응답, 보안 요건을 기술하세요. 애플리케이션과 게이트웨이는 선언된 요건을 실제로 집행해야 합니다.
| 요소 | 기술 내용 | 추가 검증 |
|---|---|---|
| 스키마 | 구조와 제약 | 실제 검증과 업무 규칙. |
| 문서화된 응답 | 기대 상태와 내용 | 실제 응답의 일치. |
| 보안 요건 | 선언한 방식과 권한 | 작업별 실효 접근 제어. |
| 예 | 하나의 설명 사례 | 일관성, 비밀 제외, 경계 사례. |
공유 전 검토
- 필수 필드, 유형, 범위, 페이지 이동, 오류, 콘텐츠 형식을 확인하세요. 비밀이나 고객 데이터 없이 스키마에 맞는 가상 예를 쓰세요.
- 통제 환경에서 설명과 실제 요청·응답을 비교하세요. 인증 누락, 권한 부족, 계정 간 격리를 시험하세요.
- 외부 참조와 이를 해석하는 도구를 검토하세요. 공개 기술에서 민감 정보를 제거하고 비공개 환경과 작업을 보호하세요.
문서를 지속 관리
변경 차이를 검토하고 담당자를 정하세요. 생성 클라이언트나 예가 구조상 맞아도 업무 규칙을 놓칠 수 있습니다. 대화형 콘솔은 적절한 환경, 제한 권한, 상태 변경 작업의 명확한 표시가 필요합니다.
1차 자료
OpenAPI와 실행 중인 서비스를 비교합니다.
유용한 OpenAPI 설명에는 클라이언트가 실제로 접하는 오류 응답, 스키마 및 예제가 포함되어야 합니다. 문서와 API가 일치하지 않으면 데모에서는 통합이 성공하더라도 실제 운영 환경에서는 실패할 수 있습니다.
- 성공 및 오류 사례를 설명과 비교합니다.
- 선택적 값, 페이지네이션 및 작업 제한 사항을 문서화합니다.
- 계약 변경 전에 대표 클라이언트를 테스트합니다.
1차 자료: IETF RFC 9457 — Problem Details for HTTP APIs. 관련 방법: 실무 가이드 읽기.
ZIP과 TAR: 디렉터리와 자원 예산 안에서 압축 해제
추출한 파일을 공개하기 전에 경로, 링크와 실제 해제량을 검증합니다.
- 최소 권한의 새 비공개 디렉터리에 추출합니다. 절대 경로, 상위 이동, 불필요한 링크와 특수 파일을 거부합니다. 실제 해석된 대상과 충돌을 대소문자를 포함한 대상 시스템 규칙으로 확인합니다. 문자열 접두사만으로 격리를 입증할 수 없습니다.
- 기록한 바이트, 항목 수, 깊이, 시간과 프로세스 자원에 파일별 및 합계 한도를 둡니다. 압축 크기나 선언 크기만 믿지 않습니다. 불필요한 중첩을 거부하고 허용 시 모든 단계가 총예산을 공유합니다. 라이브러리와 필터를 갱신합니다.
- ../, 절대 경로, 링크, 중복과 예산 초과를 시험합니다. 중단 시 배치를 공개하지 않고 기존 파일을 덮어쓰지 않아야 합니다. 유형과 내용을 검증한 후 공개하고 격리 디렉터리 정리 시 대상을 확인합니다.
재현 가능한 수락 사례
가상 예시입니다. 고객이나 실제 관측 결과를 나타내지 않습니다.
사례 입력 보기
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}예상 판단
가상 예: 2 MB 압축 데이터가 600 MB로 늘어나며 예산은 100 MB입니다. 실제 기록량 초과 시 중단하고 앞 파일이 정상 같아도 공개하지 않습니다.
Python — tarfile extraction filters and further verification
작은 압축 파일이나 필터가 안전을 보장하나요?
아닙니다. 크게 늘어날 수 있습니다. 자원 한도, 경로 규칙과 추출 파일 검증을 추가하세요.
1차 자료: Python — tarfile extraction filters and further verification. 관련 방법: 실무 가이드 읽기.
API 오류: 유형, 상태 및 증거
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5