API 호환성 정책 및 지원 중단 정책

호환성 정책

이전 버전 또는 주요 변경사항과 호환 가능

기존 API 리소스를 확장할 수 있는 리소스 URI 추가

이 변경은 일반적으로 안전합니다. 그러나 변경 시 이 변경과 충돌하는 코드를 생성할 수 있는 인기 있는 클라이언트 프레임워크를 고려해야 합니다. 다음 예제는 클라이언트 생성 코드를 손상시킬 수 있는 변경 유형입니다.

• API는 /v1.0/foo/bar에 있습니다. 코드 생성기는 클라이언트 메소드로 GetBar을 생성할 수 있습니다. 새 API가 /v1.0/foo/{param}에 도입된 경우(여기서 {param}은 임의의 문자열), 코드 생성기는 새 클라이언트 메소드를 GetFoo(String param)로 생성할 수 있습니다. GetBar에 임베드된 로직이 더 이상 호출되지 않기 때문에 이 변경으로 인해 클라이언트에 주요 변경이 발생할 수 있습니다.
• 현재 경로 /v1.0/foo/bar이 클라이언트 생성 코드 GetBar 및 GetBarAsync가 될 수 있습니다. API /v1.0/foo/Async의 추가는 이 생성된 코드와 충돌합니다.

API 인터페이스에 HTTP 메소드 추가

이 변경은 이 변경 이전의 요청 페이로드가 계속 존재하고 동일한 방식으로 작동하는 조건에서 안전합니다. 선택적 필드를 기존 API의 요청 본문에 추가하거나 조회 문자열 매개변수로 추가할 수 있습니다.

선택적 요청 헤더 추가

이 변경은 이 변경 이전의 요청이 동일한 방식으로 계속 응답하는 조건에서 안전합니다.

기존 특성에 허용된 값 추가

API 모델은 문자열을 사용하여 제한된 값 목록을 허용하는 특성을 표시합니다. 예를 들어, 리소스의 type을 문서화하여 현재 리소스 유형 목록을 나열할 수 있습니다. 클라이언트는 잘 정의되어 있는 enum 유형의 엄격한 역직렬화를 사용하는 대신 이러한 유형에 대해 일반 문자열을 사용할 것으로 예상됩니다. 가능한 값이 여러 개 있는 특성을 허용하는 리소스를 향상시켜 더 많은 값을 허용할 수 있습니다. 이 새 값은 해당하는 새 특성 및 유효성 검증 규칙을 도입할 수 있습니다. 클라이언트는 예를 들어 올바르지 않은 enum 값으로 요청하고 오류 응답을 예상하여 존재하지 않는 enum 값에 대해 유효성을 검증하지 않도록 해야 합니다.

기존 특성 값은 기존 작동을 계속 지원합니다. 예를 들어 리소스 유형에 대한 분기 로직을 포함하는 모든 클라이언트 코드는 이전과 같이 계속 작동합니다.

응답에 선택적 필드 또는 헤더, 또는 둘 다 추가

선택적 필드와 헤더는 언제든지 API 응답에 추가될 수 있습니다. 클라이언트는 이러한 변경에 대해 조정해야 합니다.

API 응답에서 오류 메시지 및 리소스 설명 변경

오류 응답의 messageId 필드는 변경할 수 없는 것으로 간주되며 항상 명시된 오류 조건 또는 케이스 목록을 항상 포함할 것으로 예상됩니다. 이 메시지와 연관된 설명은 사용자에게 메시지의 시맨틱 의미를 변경하지 않고 변경될 수 있습니다.

클라이언트는 messageDescription 속성을 기반으로 로직을 빌드해서는 안됩니다.

오류 메시지 ID 범위 늘리기

messageId 필드는 하나 이상의 오류 조건을 나타냅니다. 이 messageId는 언제든지 더 많은 오류 조건을 포함하도록 확장될 수 있습니다. 그러나 이러한 확장은 논리적이고 임의적이지 않을 것으로 예상됩니다. 새 오류 조건은 이 메시지에 포함된 기존 오류 조건과 밀접하게 관련되어야 합니다.

속도 제한 헤더 및 오류

속도 제한은 API 수명 동안 API 엔드포인트에서 조정할 수 있으며 버전 업데이트가 필요하지 않습니다.

너무 많은 요청에 대해 HTTP 상태 코드 429를 수신하는 클라이언트는 조정해야 합니다.

주요 변경사항

API 리소스 엔드포인트 또는 HTTP 메소드 제거 또는 이름 바꾸기

이 유형의 변경은 API를 사용하는 모든 클라이언트를 중단하며 이 변경을 수행하기 위한 강력한 보안이 필요한 경우가 아니면 허용되지 않습니다. 이러한 변경을 피하도록 모든 노력을 기울입니다.

enum 값 제거 또는 이름 바꾸기

enum의 값은 추가할 수 있지만 제거할 수는 없습니다.

필드의 type 변경

일반적으로 필드의 type은 변경되지 않아야 합니다. 그러나 API 구현에서 이전 type을 수락하고 이전 type으로 응답할 수 있는 경우 이 변경은 이전 버전과 호환되는 것으로 간주됩니다.

기존 요청의 가시적인 작동 변경

이전에 요청으로 인해 특정 조치 또는 응답이 발생한 경우 계속 이러한 방식으로 작동되어야 합니다. 유일한 예외는 새 오류 메시지, HTTP 상태 코드 및 요청 또는 응답 필드의 양식으로 기존 계약에 허용되는 확장입니다.

지원 중단 정책