참고 자료 · 33
클라이언트를 잃지 않고 API 계약을 발전시키십시오.
요청, 응답 및 오류를 설명하고, 버전을 테스트하고, 웹훅을 안전하게 재실행할 수 있도록 하십시오.
업데이트됨 · 17 min
이 가이드가 달성하는 목표
- 계약서 작성
- 오류 수정
- 호환성 테스트
- 서비스 종료 계획 수립
빠른 확인
- 각 작업은 어떤 클라이언트가 사용하는가?
- 오류 유형과 상태가 안정적인가?
- 기존 클라이언트가 변경 사항을 수용할 수 있는가?
- 재시도 시 작업이 중복될 수 있는가?
- 서비스 종료는 어떻게 발표하고 검증할 것인가?
단계별 방법
- 1
사용자 목록 작성
작업, 클라이언트, 사용량, 버전 및 소유자 목록을 작성합니다. 필드를 변경하기 전에 관찰된 사용량과 가정을 구분합니다.
결과물: 계약 종속성 맵
- 2
요청 및 응답 설명
스키마, 실제 예제, 성공 및 실패 응답을 포함하는 OpenAPI 설명을 유지 관리합니다. 실행 중인 서비스와 비교하여 검증합니다.
결과물: 버전 관리된 계약 및 적합성 테스트.
- 3
오류 안정화
HTTP 상태를 의미론에 따라 사용하고, 필요한 경우 RFC 9457에 따라 문서화된 문제 유형을 사용합니다. 비밀 정보를 자세히 노출하지 않습니다.
결과물: 테스트된 오류 카탈로그.
- 4
변경 사항 분류
필수 필드, 유형, 값, 동작, 시간 초과 및 페이지네이션을 검사합니다. 대표적인 사례를 사용하여 이전 클라이언트를 새 버전과 비교하여 테스트합니다.
결과물: 호환성 매트릭스 및 버전 결정.
- 5
알림의 안정성 확보
웹훅의 경우 인증, 비정렬 전송, 중복 및 재시도 계획을 수립합니다. 반복이 가능한 경우 처리의 멱등성을 확보합니다.
결과물: 재실행 및 승인 시나리오.
- 6
종료 경로를 포함한 릴리스
마이그레이션 노트, 공존 기간 및 연락처를 게시합니다. 이전 버전 사용량을 측정하고 영향을 받는 사용자를 확인한 후에만 이전 버전을 폐기합니다.
결과물: 마이그레이션 계획 및 폐기 증빙 자료 종료 경로를 포함한 릴리스 이전 버전 배포 마이그레이션 노트, 공존 기간 및 연락처를 게시합니다. 이전 버전 사용량을 측정하고 영향을 받는 사용자를 확인한 후에만 이전 버전을 폐기합니다. 최종 결과물: 마이그레이션 계획 및 이전 버전
관리 지표
| 지표 | 측정 대상 | 첫 번째 조치 |
|---|---|---|
| 계약 | 설명된 작업 및 서비스 동작 일치 | 차이점 수정 |
| 호환성 | 변경 전 대표 클라이언트 테스트 완료 | 누락된 사례 추가 |
| 오류 | 민감한 데이터가 없는 유형 문서화 | 메시지 및 스키마 수정 |
| 마이그레이션 | 소유자가 있는 이전 버전 사용 | 나머지 클라이언트 지원 |
일반적인 실수
- 버전 번호만으로 호환성이 유지된다고 가정
- 200개의 응답만 문서화
- 오류 발생 시 내부 추적 또는 비밀 키 반환
- 웹훅이 한 번만 순서대로 도착한다고 가정
자주 묻는 질문
OpenAPI가 테스트를 대체합니까?
아니요. 설명과 실제 응답 및 소비자 요구 사항을 비교하십시오.
모든 변경 사항에 새 버전이 필요합니까?
아니요. 클라이언트 영향 및 계약 동작을 기준으로 결정하십시오. 호환되지 않는 변경 사항에는 명확한 계획이 필요합니다.
오타는 왜 발생할까요?
오타는 고객에게 문제를 구분하고 조치를 선택할 수 있는 안정적인 방법을 제공합니다.
ETag, HTTP 캐시 및 동시 변경
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Two clients, three versions: make a conflict visible
In this fictional scenario A and B edit the same representation. The server emits a strong ETag for each newly stored version. If-Match rejects a modification based on a version that is no longer current. These five explanatory excerpts make no connection and perform no real write.
1. A reads the initial version
A receives representation v1 and keeps "v1" with the data being edited. A copied tag without its representation is insufficient to understand a conflict.
Request excerpt
GET /demo/resource HTTP/1.1
Host: api.example.testResponse excerpt
HTTP/1.1 200 OK
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v1"2. B saves before A
B has also read v1. Its PUT satisfies If-Match: "v1". The exact new representation is stored as "v2"; this server returns 204 with the new validator.
Request excerpt
PUT /demo/resource HTTP/1.1
Host: api.example.test
If-Match: "v1"Response excerpt
HTTP/1.1 204 No Content
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v2"3. A attempts a stale write
The current version is now v2. A still sends If-Match: "v1": 412, without applying its modification. Preserve local work for comparison.
Request excerpt
PUT /demo/resource HTTP/1.1
Host: api.example.test
If-Match: "v1"Response excerpt
HTTP/1.1 412 Precondition Failed
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store4. A reads again and resolves the conflict
A retrieves v2 and compares its original data, local edits and the current version. A person or an explicit business rule chooses which changes to retain.
Request excerpt
GET /demo/resource HTTP/1.1
Host: api.example.testResponse excerpt
HTTP/1.1 200 OK
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v2"5. A submits a reconciled modification
After that decision, A sends the revised proposal with If-Match: "v2". It succeeds in this scenario and creates v3. Another concurrent writer could still require another cycle.
Request excerpt
PUT /demo/resource HTTP/1.1
Host: api.example.test
If-Match: "v2"Response excerpt
HTTP/1.1 204 No Content
Date: Thu, 22 Oct 2026 00:00:00 GMT
Cache-Control: no-store
ETag: "v3"Fictional HTTP/1.1 excerpts: request and response bodies are omitted even where allowed. HEAD, 204 and 304 have no response content. The api.example.test domain and fixed date serve only to explain this scenario.
The protocol detects a stale version; it does not decide how to merge content. Document what the interface retains after 412, who resolves the conflict and when a fresh read is needed. If-Match: * does not replace comparison of a specific strong ETag.
Explore ETag comparisons and the simulator →
Primary references and limits
The standards define HTTP conditions and caching. The ten cases, laboratory and two-client walkthrough are original illustrations. Displayed results are calculated by this local model, not measurements of this site or your infrastructure.
- IETF · RFC 9110 — HTTP Semantics · June 2022 · STD 97
§8.8.3.2; §13.1.1–13.1.2; §13.2; §15.3.5; §15.4.5 - IETF · RFC 9111 — HTTP Caching · June 2022 · STD 98
§4.1; §4.3; §5.2.2.4–5.2.2.5; §5.2.2.7 - IETF · RFC 6585 — Additional HTTP Status Codes · April 2012 · Standards Track
§3 · 428 Precondition Required
References reviewed
Retry-After: 대기, 예산 및 재시도 결정
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Specify permission to repeat before retry timing
Retry-After describes waiting. The contract must also define replayable operations, keys, versions and unknown-result states.
- State whether the field is seconds or a date and how clients handle absent or invalid values.
- Name the retry controller and global budget to prevent overlapping attempts.
- Retain parameters, context and the idempotency window without generalising Stripe to every API.
Explore Retry-After and the retry model →
References reviewed · RFC 9110 · §9.2.2, §10.2.3 · RFC 6585 · §4 · AWS
OAuth/OIDC: 대상과 권한
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
An API contract must name its audience and permissions
Bind the route to an expected resource, explicit scopes and an object rule. Signature verification alone does not establish this contract.
- Document accepted profiles and separate access tokens, ID tokens and opaque tokens.
- Test a token intended for another API, missing scope and another tenant’s object.
- Return a controlled denial and keep traces free of codes and tokens.
See token recipients and the ten OAuth/OIDC cases →
Sources reviewed on · IETF · RFC 9700 · OAuth 2.0 Security BCP · IETF · RFC 9068 · JWT access token profile · OpenID Foundation · OpenID Connect Core 1.0 · IETF · RFC 8725 · JWT Best Current Practices · IETF · RFC 6749 · OAuth 2.0 framework
웹훅: 서명과 재전송
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
The contract must define the exact authenticated bytes
Stripe and GitHub do not use the same HMAC message. Record the header, raw body, trusted keys and freshness policy without generalising one provider’s profile.
- Test a reformatted body with its original signature.
- Separate cryptographic validation, freshness and duplicate recognition.
- Document durable acknowledgement and business status with distinct evidence.
See webhook signatures, digests and the ten cases →
Sources reviewed on · Stripe · Webhooks · Stripe · Manage webhook endpoints · GitHub · Validating webhook deliveries · GitHub · Best practices for using webhooks · GitHub · Handling failed webhook deliveries
API 오류: 유형, 상태 및 증거
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
A useful API error connects a stable problem type, an occurrence and a possible client action. RFC 9457, published in July 2023 to replace RFC 7807, supplies a common format. It does not turn an error message into authorisation evidence, replay instructions or a complete security diagnosis.
Five explained standard members, six problem types in the IANA snapshot updated 26 June 2026, and eight fictional acceptance cases. Sources consulted 23 October 2026. Examples and proposed tests are original CIE material.
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5
Five members: role and client-side reading
| Member | Expected type | Role | Acceptance question |
|---|---|---|---|
| type | string · URI reference | Identifies the problem type; defaults to about:blank if absent. | Does the client decide using the URI rather than a translated title? |
| status | number · HTTP status | Restates the status for this occurrence; advisory. | Do body and response status agree? |
| title | string | Human-readable summary of the problem type. | Does localisation change only person-facing text? |
| detail | string | Human-readable explanation of this occurrence. | Does the client avoid parsing prose as a machine code? |
| instance | string · URI reference | Identifies a particular occurrence. | Does the reference support follow-up without exposing internal details? |
These members are optional. Consumers must ignore a member with an unexpected JSON type. They must also tolerate unrecognised extensions. The specified JSON media type is application/problem+json.
읽기 실습
Select one of eight examples, then optionally change the assumed received HTTP status. The body and media type remain those of the chosen case. This workshop compares limited facts; it validates neither all URIs, business schemas, authorisation nor a real service. The media-type name is compared without validating all its parameters. HTTP method and other transport rules still need checking.
Only the fictional examples displayed below are used. URIs are shown as text: none is automatically visited or resolved. No production log or message is requested.
100~599의 반각 숫자 세 자리를 입력하세요.
비교 결과
Content-Type: application/problem+json
Fictional JSON body
{
"type": "https://api.example.net/problems/invalid-window",
"title": "Invalid time window",
"status": 422,
"detail": "The end must follow the start.",
"instance": "/problems/events/test-17",
"errors": [
{
"field": "end",
"code": "before-start"
}
]
}Six registered types: preserve exact URIs and references
This common-type registry is not a list of every problem an API can define. N/A for about:blank is not an HTTP status. The three digest entries retain a draft-kind reference as published in this IANA snapshot; this is not rewritten as a final RFC number.
IANA · HTTP Problem Types · Registry updated 2026-06-26 · consulted 2026-10-23
| Type URI and IANA title | Recommended status | Reference as published | Registration date |
|---|---|---|---|
about:blankSee HTTP Status Code | N/A | rfc · rfc9457 | 2023-05-02 |
https://iana.org/assignments/http-problem-types#dateDate Not Acceptable | 400 | rfc · rfc9458 · §6.5.2 | 2023-05-02 |
https://iana.org/assignments/http-problem-types#ohttp-keyOblivious HTTP key configuration not acceptable | 400 | rfc · rfc9458 · §5.3 | 2023-05-02 |
https://iana.org/assignments/http-problem-types#digest-unsupported-algorithmsUnsupported Hashing Algorithms | 400 | draft · RFC-ietf-httpapi-digest-fields-problem-types-06 · §3.1 | 2026-06-26 |
https://iana.org/assignments/http-problem-types#digest-invalid-valuesInvalid Digest Values | 400 | draft · RFC-ietf-httpapi-digest-fields-problem-types-06 · §3.2 | 2026-06-26 |
https://iana.org/assignments/http-problem-types#digest-mismatched-valuesMismatched Digest Values | 400 | draft · RFC-ietf-httpapi-digest-fields-problem-types-06 · §3.3 | 2026-06-26 |
IANA · Protocol Registries licensing · CC0 1.0 · Revised 2021-11-10 · CIE commentary and fictional examples identified separately
Eight cases and acceptance decisions
P01 · An explicit business problem type
HTTP 422 · Content-Type: application/problem+json
{
"type": "https://api.example.net/problems/invalid-window",
"title": "Invalid time window",
"status": 422,
"detail": "The end must follow the start.",
"instance": "/problems/events/test-17",
"errors": [
{
"field": "end",
"code": "before-start"
}
]
}Reading : Body and response statuses agree. The errors array is an extension specific to this example, not a universal standard member.
Test to add : Test the stable before-start code and field association; do not parse detail prose to automate correction.
P02 · Type and status omitted
HTTP 404 · Content-Type: application/problem+json
{
"title": "Ressource introuvable",
"instance": "/support/test-18"
}Reading : The five members are not an all-required checklist. Without a usable type, about:blank applies; the received HTTP status remains 404.
Test to add : Check that the client accepts this minimal response and a localised title without inventing a body status.
P03 · Body says 403 but HTTP says 200
HTTP 200 · Content-Type: application/problem+json
{
"type": "https://api.example.net/problems/access-denied",
"title": "Access denied",
"status": 403
}Reading : Two layers disagree. The advisory JSON status does not replace the status received by generic HTTP clients.
Test to add : Investigate generation and intermediaries; preserve both values rather than declare success from HTTP 200 alone.
P04 · Five members with the wrong JSON type
HTTP 422 · Content-Type: application/problem+json
{
"type": 17,
"title": false,
"status": "422",
"detail": [
"Invalid"
],
"instance": null,
"traceRef": "test-19"
}Reading : type, title, status, detail and instance have unexpected types. RFC consumer handling is to ignore them rather than coerce the string "422" into a number.
Test to add : Report the producer defect and test a tolerant client. traceRef remains an extension; about:blank is the default after type is ignored.
P05 · Relative URI and unknown extensions
HTTP 409 · Content-Type: application/problem+json
{
"type": "/problems/conflict",
"title": "Version conflict",
"status": 409,
"instance": "?case=test-20",
"requestRef": "test-20",
"retryable": false
}Reading : The type uses a relative path and instance a query reference. This workshop displays them without resolution; the real document base would be required.
Test to add : Define the contract base, prefer an absolute type and test ignored unrecognised extensions. The word retryable alone does not grant universal replay safety.
P06 · An exact registered URI
HTTP 400 · Content-Type: application/problem+json
{
"type": "https://iana.org/assignments/http-problem-types#date",
"title": "Date Not Acceptable",
"status": 400,
"instance": "/support/test-21"
}Reading : This type appears in the IANA snapshot. Its recommended status is 400. Comparing only #date or title does not identify the type.
Test to add : Refer the client to this type’s definition in its applicable context; registration does not certify an implementation.
P07 · A similar object with another media type
HTTP 503 · Content-Type: application/json
{
"type": "https://api.example.net/problems/maintenance",
"title": "Service maintenance",
"status": 503,
"detail": "Try the documented recovery path."
}Reading : The body resembles Problem Details, but the received media-type name is application/json. Structural reading does not verify negotiation or the response contract.
Test to add : Compare Content-Type, documentation and client. This example is not a retry rule: Retry-After and replay safety remain separate checks.
P08 · A number is not sufficient for an HTTP status
HTTP 400 · Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Bad Request",
"status": 700,
"instance": "/support/test-22"
}Reading : status is a JSON number, but 700 lies outside the HTTP three-digit range 100–599. This differs from having the wrong JSON type.
Test to add : Repair generation and preserve the received HTTP status, 400 here. A data-type-only check would have missed this anomaly.
IETF · RFC 9110 · HTTP Semantics · June 2022 · §6.4.1, §15, §15.3.6 · status range and response content
Evolve an error without breaking its contract
| Proposed change | Practical client risk | Recommended CIE exercise |
|---|---|---|
| Localise title or detail | A client parsing the phrase may take a different branch. | Keep the same type and replay two languages with the same expected machine outcome. |
| Change the type URI | A new problem identity may replace the old one. | Test existing consumers and document migration, tolerance and fallback. |
| Add an extension | An overly strict client may reject a previously readable response. | Add an unknown member to the consumer test and check the intended tolerance. |
| Remove or rename a business extension | A client action may depend on the documented field. | Check the type-specific contract, observed use and compatibility plan. |
| Change the HTTP status | A proxy, cache or SDK may handle the response differently. | Compare raw response and body through generation and intermediaries. |
| Add technical detail | Internal paths, secrets or account information may leak. | Test the public message, occurrence reference and access-controlled logs separately. |
Keep a raw response example for each refusal, its type definition, the consumer test outcome and contract version. Two matching numbers do not demonstrate that the server chose the correct refusal or that another attempt has no side effects.
Provenance and snapshot limits
IANA · 6 types · registry 2026-06-26 · reviewed 2026-10-23 · CC0 1.0
IANA XML SHA-256: 2b6a7ae5a63a5f6afccd8884658393d5268d16b63d624e883fd5fe5dcf5aa57b
RFC 9457 TXT SHA-256: f2b3db92fb0bf3489cb3841a0da0c0d88dff40797b64d40b6123085183886c7b
GraphQL: 오류, 목록 및 부분 데이터
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
GraphQL contract: errors do not always erase data
Define what a client may retain after resolver failure: the contract includes data shape, null scope and error paths.
- Compare absent data, partial data and data: null.
- Keep the original path even when a parent becomes null.
- Test permissions, quotas and interface states separately.
Explore GraphQL responses and nullability →
GraphQL Specification · September 2025 · Published edition · September 2025
API 사용 중단과 종료
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23
공식 참조
참조는 방법을 뒷받침합니다. 상황에 맞게 검사를 조정하십시오. 이는 인증이 아닙니다. 원본 참조 제목 및 소스 문서는 다른 언어로 작성되었을 수 있습니다.
참고 자료 확인일 .
- OpenAPI Specification 3.1.1
- IETF RFC 9457 — Problem Details for HTTP APIs
- IETF · RFC 9110 — HTTP Semantics
- IETF · RFC 9111 — HTTP Caching
- IETF · RFC 6585 — Additional HTTP Status Codes
- IETF · RFC 9700 · OAuth 2.0 Security BCP
- IETF · RFC 9068 · JWT access token profile
- OpenID Foundation · OpenID Connect Core 1.0
- IETF · RFC 8725 · JWT Best Current Practices
- IETF · RFC 6749 · OAuth 2.0 framework
- Stripe · Webhooks
- Stripe · Manage webhook endpoints
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- IETF · RFC 9745 · Deprecation
- IETF · RFC 8594 · Sunset
- GraphQL Specification · September 2025
- IANA · HTTP Problem Types
- IETF · RFC 9110 · HTTP Semantics
- AWS Builders’ Library · Timeouts, retries, and backoff with jitter
- Stripe · Idempotent requests
- Stripe · API v2 overview — Idempotency
- Stripe · Advanced error handling
