유한 옵션 세트에 추가; API 주요 변경 사항?

9

다음 응답 모델을 추출하는 HTTP API 엔드 포인트를 가져 오십시오.

{
    "type": "Dog",
    "name": "Jessi",
    ...
}

이 type필드는 설명서 Dog에서 Cat또는 중 하나 인 것으로 설명되었습니다 Fish.

새로운 옵션을 추가하는 Rat것이 API의 주요 변경으로 간주됩니까?

유한 목록에 옵션을 추가합니까 (개발자가 켤 수있는) API의 확장 또는 수정으로 간주됩니까?

— 데이브 뉴
소스

10

설명서에서이 필드가 Dog, Cat 또는 Fish 중 하나로 설명 된 경우 다른 유형을 추가하면 이전 버전과 호환되지 않는 방식으로 인터페이스가 변경됩니다. API 소비자는 개와 고양이를 물고기와 다르게 다루기 위해 특정 코드를 작성했음을 전적으로 생각할 수 있습니다. 알 수없는 유형이 주어지면 해당 소비자는 응답으로 무엇을해야할지 모릅니다. 그러나 이것은 실제 문제 영역에서 "Cat"및 "Fish"플레이스 홀더 유형이 무엇을 나타내는 지에 달려 있습니다.

가능한 유형 목록에 대한 변경이 빈번하거나 목록이 유한하지 않은 경우에는이를 문서화하는 것이 좋습니다. 사용 사례에 따라 가능한 모든 유형 목록을 API의 엔드 포인트로 공개하는 것이 좋을 수 있습니다. 따라서 API 버전을 업데이트하지 않고도 유형을 추가하거나 제거 할 수 있습니다. 그러나 유형이 동적 일수록 API 소비자가 유형별 작업을 수행하기가 더 어려워집니다. 확장 성 또는 사용 편의성이 더 중요한지 여부는 사용 사례와 문제 영역에 따라 다릅니다.

— 아몬
소스

환상적인 답변-감사합니다. 문서에 "다음 표에 현재 API 에서 지원 되는 동물이 설명되어 있습니다"라는 제목의 옵션이 자세히 설명되어 있으면 어떻게됩니까? 옵션이 확장 될 수 있음을 나타내지 않습니까?

— Dave New

1

@davenewza 아마 좋은 생각이지만 좀 더 명확 할 것입니다. 당신이 의미하는 바를 나타내지 말고 직접 말하십시오! 다음과 같이 명확한 기대치를 설정 하고 해당 엔드 포인트에 대한 문서에서 안정성을 보장 하려고합니다 . 이 경우 API의 부 버전 번호가 업데이트됩니다. "

— amon

실행 가능한 사양 >>> 문서화 된 사양 >>> 문서화되지 않은 사양.

— VoiceOfUnreason

0

기존 작업에서 "Rat"을 반환 할 수있는 경우에만 중단됩니다.

기존 작업에서 "Rat"을 반환 할 수 없으면이 새 옵션을 추가해도 아무런 영향이 없습니다.

— 존 레이너
소스