FedEx API 버저닝

FedEx에서는 API 버전 관리에 있어 유의적 버저닝을 사용합니다. 각 버전은 메이저.마이너(major.minor)와 같은 형식으로 표시됩니다(예, Ship API 1.1). 새 메이저 버전은 변경 사항이 이전 버전과 호환되지 않으며, 새로운 마이너 버전은 변경 사항이 이전 버전과 호환됨을 의미합니다.

FedEx에서는 단순한 URI 버저닝을 사용합니다. URI 경로에는 메이저 버전 번호만 표시되며, 마이너 버전 번호는 URI 경로에 포함되지 않는다는 점에 유의하십시오. 이 같은 전략은 URI 라우팅을 사용하여 특정 버전의 API를 정확하게 찾아낼 수 있습니다.

예: /ship/v1/shipments

버저닝 전략 기본 원칙

FedEx에서는 FedEx API 메이저 버전의 출시 빈도를 줄일 예정이며, 새로운 메이저 버전이 공개된 후 2년 후에는 기존의 메이저 버전을 사용하지 못하게 됩니다. 예를 들어 메이저 버전 ‘N’이 출시된다면, ‘N-1’ 버전은 그 뒤로 2년 동안 지원됩니다.

예: 2020년에 메이저 버전 V1.0이 출시됩니다. 그런 다음 2021년에 메이저 버전 V2.0이 출시되면 2023년에는 V1.0을 더 이상 사용할 수 없게 됩니다.

마이너 버전에서 대부분의 새로운 특징 및 기능 업데이트를 지원합니다.

예: 포스트 메이저 버전 1.0, 마이너 버전 1.1, 1.2 등이 출시되어 새로운 특징 및 기능 업데이트를 제공합니다.

어떤 시점에서든 특정 API의 모든 엔드포인트는 동일한 메이저 버전을 갖게 됩니다. 최신 버전의 설명서는 FedEx Developer Portal에서만 이용할 수 있습니다. 하지만 각 API의 개요 페이지 아래 메이저 및 마이너 버전의 변경 사항을 자세하게 설명한 변경 로그가 제공될 것입니다.

API 메이저 버전은 언제 출시됩니까?

FedEx에서는 새 메이저 버전의 API 출시 빈도를 최소화하기 위해 고군분투하고 있습니다. 그러나 새 메이저 버전의 출시가 불가피한 경우도 있습니다. 다음은 새 메이저 버전이 출시되는 몇 가지 주요 이유입니다.

• 기존 열거 값이 제거되거나, 형식 또는 값 자체가 요청이나 응답에서 변경되었을 때.
  

  예: locationSearchCriterion 요소의 열거 값 “GEOGRAPHIC_COORDINATES”가 N 버전에서 제거됨, 날짜 구문이 YY-MM-DD에서 MM-DD-YYYY로 변경됨, 응답에서 사무소 유형이 FEDEX_ONSITE에서 ONSITE로 변경됨

• 기존 요소가 요청이나 응답에서 제거되었을 때.
  

  예: pickupType 요소가 N 버전의 운임 요청에서 제거됨(혹은 이름이 변경됨)

• 기존 메서드가 제거되었을 때.
  

  예: FedEx Express Tag를 생성 및 취소하는 메서드가 N 버전에서 더 이상 지원되지 않음.

• 선택 사항 또는 조건부였던 기존 요소가 요청에서 필수 사항이 되었을 때.
  

  예: N 버전에서 FedEx Express® Freight 화물의 예약 번호가 필수 요소가 됨.

• API 디자인에 변경 사항이 있을 때.
  

  예: 요청 및 응답 구조가 재조정됨.

• 오류 코드 및 오류 메시지가 표시된 변경 사항이 있을 때.
  

  예: 오류 코드가 INCORRECT.WEIGHT에서 WEIGHT.LIMIT.EXCEEDED로 변경됨.

API 마이너 버전은 언제 출시됩니까?

• 새 열거 값이 추가되었을 때.
  

  예: N 버전의 serviceType 요소에 새 운송 서비스가 추가됨.

• 새 요소가 추가되었을 때.
  

  예: 국제 발송을 위해 관세사 전화 번호를 포함하는 새로운 선택 사항이 추가됨

• 새 메서드가 추가되었을 때.
  

  예: 국제상거래 문서를 업로드한 뒤 수정하는 메서드가 N 버전에 추가됨.

• 필수 사항이었던 기존 요소가 선택 사항이 되었을 때.
  

  예: FedEx가 사용자 정보를 기반으로 문서 ID를 가져올 수 있게 되어 문서 ID가 선택 사항이 됨.