이전 버전과의 호환성 가이드라인

각 YouTube Data API 요청은 YouTube에서 해당 요청을 처리하는 데 사용할 API 버전을 지정할 수 있습니다. 요청에서 API 버전을 지정하지 않으면 YouTube는 지원되는 가장 오래된 API 버전을 사용하여 해당 요청을 처리합니다. 현재 지원되는 가장 오래된 버전은 1입니다. API 버전 번호의 다음 특성에 유의하세요.

• YouTube는 출시에 새 버전 번호가 할당되지 않은 특정 API 버전의 업데이트를 출시할 수 있습니다. 이러한 하위 호환 업데이트에는 선택적 API 기능, 버그 수정 또는 둘 다 포함될 수 있습니다.

• API 버전 번호가 증가하면 이전 API 버전과 호환되지 않는 변경사항이 포함된 출시가 식별됩니다.

이 문서에서는 위에 나열된 첫 번째 항목인 특정 API 버전 업데이트에 관한 하위 호환성 가이드라인을 정의합니다. 이 가이드라인은 다음과 같은 유형의 API 기능을 구분하는 것을 목표로 합니다.

• 이 가이드라인에서는 API 요청을 처리하는 데 사용해야 하는 API 버전을 수정하지 않더라도 변경될 수 있는 API 기능을 식별합니다. 코드는 이러한 변경사항을 중단 없이 처리해야 합니다. 예를 들어 YouTube가 API 응답에 새 XML 태그를 추가하는 경우 코드는 이러한 태그를 무시해야 합니다.

• 또한 이 가이드라인에서는 특정 API 버전을 업데이트할 때 YouTube에서 변경할 의도가 없는 API 기능을 정의합니다. 즉, YouTube에서 새 API 버전을 출시하는 경우에만 기능이 변경될 것으로 예상해야 하며 코드에서 이러한 유형의 변경사항을 처리할 필요가 없습니다.

이 문서에 관한 정보

이 도움말에는 다음과 같은 섹션이 있습니다.

• API 요청 섹션에서는 HTTP 요청 헤더, API 요청 매개변수, XML 요소 이름 (API 요청에 표시됨), 잘못된 형식의 API 요청과 관련된 하위 호환성 가이드라인을 정의합니다.

• API 응답 섹션에서는 XML 요소 이름 (API 응답에 표시되는 대로) 및 XML 태그와 속성이 API 응답에 표시되는 순서와 관련된 이전 버전과의 호환성 가이드라인을 정의합니다.

• 권장사항 섹션에서는 YouTube API를 클라이언트 애플리케이션과 통합하기 위한 권장사항을 간략히 설명합니다.

API 요청

변경되지 않을 기능

• 기존 요청 매개변수

• 열거된 값이 있거나 이러한 매개변수 값의 의미가 있는 매개변수의 기존 매개변수 값

• API POST (삽입) 또는 PUT (업데이트) 요청에 사용되는 XML 요소의 이름입니다.

• 각 유형의 API 요청에 필요한 HTTP 요청 헤더 집합입니다. 이 가이드라인은 YouTube에서 필수 HTTP 요청 헤더를 추가하거나 기존의 선택적 요청 헤더를 필수로 변경할 계획이 없음을 의미합니다.

• 요청이 strict 매개변수를 사용하지 않는 한 API 요청에서 지원되지 않는 매개변수를 무시하는 동작으로, YouTube에 잘못된 요청 매개변수가 포함된 API 요청을 거부하도록 지시합니다.

변경될 수 있는 기능

• YouTube에서 선택적 요청 매개변수를 추가할 수 있습니다.

• YouTube는 값 집합이 열거된 기존 매개변수에 새 값을 추가할 수 있습니다.

• 유효한 매개변수에 잘못된 매개변수 값이 포함된 요청은 YouTube에서 거부할 수 있습니다. 따라서 지나치게 관대한 파싱으로 인해 허용된 잘못된 형식의 요청은 파싱 로직이 수정되면 거부될 수 있습니다.

• YouTube에서 선택적 HTTP 요청 헤더를 추가할 수 있습니다.

• YouTube는 리소스를 삽입하거나 업데이트할 때 보관 (저장)하는 정보를 변경할 수 있습니다. 그러나 이러한 결정은 상응하는 API 요청의 문법에 영향을 미치지 않으며 이를 변경할 필요도 없습니다.

• YouTube는 탐색 가능한 카테고리 집합 또는 새로 업로드된 동영상을 할당할 수 있는 카테고리 집합을 변경할 수 있습니다.

• 문서화되지 않은 기능은 언제든지 삭제되거나 변경될 수 있습니다.

API 응답

변경되지 않을 기능

• 기존 XML 태그 이름

• 미디어 RSS 사양에 따라 해당 사양에 정의되어 있고 피드 항목에 여러 번 표시되는 요소의 순서를 결정합니다. 예를 들어 항목에 여러 개의 <media:thumbnail> 태그가 포함된 경우 중요도순으로 정렬됩니다.

• 피드 또는 피드 항목에 설명된 항목 유형을 식별하는 <category> 태그의 term 속성 값입니다. <feed> 또는 <entry> 태그 내에서 <id> 태그는 항목으로 식별된 고유한 리소스를 지정하고 <category> 태그는 항목으로 설명된 리소스 유형을 식별합니다. 이 <category> 태그의 경우 scheme 속성 값은 http://schemas.google.com/g/2005#kind이고 term 속성 값은 피드 항목이 동영상, 재생목록 링크, 구독, 연락처 또는 다른 항목 유형을 설명하는지 여부를 나타냅니다.

변경될 수 있는 기능

• YouTube에서 API 응답에 새 XML 태그를 추가할 수 있습니다.

• YouTube에서 기존 XML 태그에 새 속성을 추가할 수 있습니다.

• 기존 API 태그는 다른 값으로 반복될 수 있습니다. 예를 들어 YouTube는 다른 type 값이 있는 새 <media:restriction> 태그 또는 다른 scheme 및 role가 있는 새 <media:credit> 태그를 추가할 수 있습니다.

• API 응답의 XML 태그 및 속성 순서가 변경될 수 있습니다.

• 선택적 하위 태그가 API 응답에서 삭제될 수 있습니다.

• 문서화되지 않은 기능은 언제든지 삭제되거나 변경될 수 있습니다.

권장사항

• <id> 태그 값을 사용하여 항목을 식별합니다.

• self 링크를 사용하여 항목을 검색합니다.

• edit 링크를 사용하여 항목을 수정하거나 업데이트합니다.

• 동영상 항목의 <yt:videoid> 태그 값을 사용하여 YouTube가 해당 동영상을 고유하게 식별하는 데 사용하는 값을 가져옵니다. 링크에서 동영상 ID를 파싱하지 마세요.

• <link>, <content>, <gd:feedLink> 태그에 식별된 URL을 사용하여 피드 간에 이동합니다. YouTube는 특정 피드를 검색하기 위해 안정적으로 구성할 수 있는 제한된 URL 집합을 지원합니다. 아래에 나열된 피드 URL 외에는 자체 피드 URL을 생성해서는 안 됩니다. 예기치 않게 작동이 중지될 수 있기 때문입니다.

  • /feeds/api/videos/<videoid>
  • /feeds/api/users/default
  • /feeds/api/users/default/uploads
  • /feeds/api/users/default/favorites
  • /feeds/api/users/default/contacts
  • /feeds/api/users/default/inbox
  • /feeds/api/users/default/playlists
  • /feeds/api/users/default/subscriptions
  • /feeds/api/users/default/newsubscriptionvideos
  • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (자세한 내용은 참조 가이드 참고)

• API 응답의 URL에서 숫자 또는 영숫자 식별자를 파싱하려고 하지 마세요. API 응답에는 동영상 ID (<yt:videoid>) 및 사용자 이름 (<name> 및 <media:credit>).)과 같이 YouTube 웹사이트의 리소스에 연결되는 식별자의 특정 태그가 포함됩니다.

• 정보를 삽입 (POST)하거나 업데이트 (PUT)하기 위한 API 요청을 제출하는 경우 해당 요청에 대한 XML 응답을 사용하여 요청의 어떤 태그 값이 YouTube에 실제로 저장되었는지 확인합니다. API 요청의 하위 호환성 가이드라인에 설명된 대로 YouTube는 리소스를 삽입하거나 업데이트할 때 보관 (저장)하는 정보를 변경할 수 있습니다. 즉, 요청의 일부 태그가 무시될 수 있습니다.

• XML 피드를 가져올 때 애플리케이션에서 사용자가 해당 항목을 업데이트할 수 있는 경우 피드 항목과 관련된 인식되지 않는 XML 태그와 속성을 저장합니다. 사용자가 리소스를 업데이트하는 경우 애플리케이션은 인식되지 않는 태그와 속성을 업데이트 요청에 포함해야 합니다. 이렇게 하면 애플리케이션이 리소스를 업데이트하는 과정에서 새 API 기능과 관련된 정보를 실수로 삭제하지 않습니다.

  다음 예는 이러한 권장사항을 보여줍니다.

  1. 애플리케이션을 사용하면 사용자가 동영상 설명을 업데이트할 수 있습니다.
  2. 애플리케이션이 API를 사용하여 동영상 항목을 가져오지만 항목의 태그 중 하나를 인식하지 못합니다.
  3. 사용자가 동영상 설명을 수정합니다.
  4. 애플리케이션은 전체 동영상 항목을 API로 다시 전송해야 합니다. 항목에 2단계의 인식되지 않는 태그가 포함되어야 합니다. 그렇지 않으면 해당 값이 삭제될 수 있습니다.

• 태그 값을 표시하려고 하기 전에 태그가 존재하고 null이 아닌 값을 포함하는지 확인합니다.

• 위에서 언급했듯이 YouTube는 값 집합이 열거된 기존 태그 또는 속성에 새 값을 추가할 수 있습니다. 일반적으로 코드는 값 집합을 열거한 XML 요소의 값을 파싱한 다음 이러한 값에 적절한 작업을 정의해야 합니다. 요소에 가능한 값이 하나만 열거된 경우에도 이 관행을 따르는 것이 좋습니다.

  예를 들어 <media:credit> 태그는 동영상의 소유자를 식별합니다. 태그의 role 속성에 대해 문서화된 유일한 값은 uploader이며 이는 동영상이 YouTube 파트너가 업로드했음을 나타냅니다. 이 권장사항에 따라 애플리케이션은 해당 사용자를 동영상 소유자로 식별하기 전에 태그의 role 속성 값이 실제로 uploader인지 확인해야 합니다. 이렇게 하면 YouTube에서 동영상에 다른 유형의 크레딧(예: 감독)을 추가할 때 코드가 동영상 소유자를 부정확하게 식별하지 않습니다.

  • 태그에 열거형 값 집합이 있고 해당 태그의 값을 인식하지 못하는 경우 해당 태그가 표시되는 전체 <entry>를 무시해야 합니다.

  • scheme 속성 값이 http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat인 <category> 태그의 term 속성 값을 인식할 수 없는 경우 구독 피드 항목을 무시합니다. 이 특정 태그는 항목에서 식별된 정기 결제 유형을 나타냅니다. 애플리케이션이 정기 결제 유형을 인식하지 못하는 경우 해당 항목에 관한 정보를 표시해서는 안 됩니다.

  • 다른 속성에 열거된 값 집합이 있고 해당 속성의 값을 인식하지 못하는 경우 속성이 표시되는 태그를 무시해야 합니다.

• 애플리케이션 코드는 언제든지 yt:error 메시지를 예상해야 합니다. API 작업이 실패하면 애플리케이션은 오류를 식별하고 사용자에게 의미 있는 메시지를 표시해야 합니다.

• YouTube는 언제든지 동영상 분류를 위한 새로운 카테고리를 추가할 수 있습니다. YouTube에서 기존 카테고리를 업데이트하거나 지원 중단할 수도 있습니다. http://gdata.youtube.com/schemas/2007/categories.cat에서 현재 카테고리 파일을 가져올 수 있습니다.

  • 애플리케이션에서 사용자가 카테고리별로 동영상을 탐색하거나 동영상을 업로드할 수 있는 경우 업데이트된 카테고리 파일을 매주 검색합니다.

  • 애플리케이션에서 사용자가 카테고리별로 동영상을 탐색할 수 있는 경우 API가 카테고리 검색에 대한 응답으로 빈 피드를 반환하는 경우 업데이트된 카테고리 파일도 가져옵니다.

  • 애플리케이션에서 사용자가 동영상을 업로드할 수 있는 경우 동영상을 업로드하기 전에 업데이트된 카테고리 파일도 가져와 업로드된 동영상과 연결된 카테고리를 계속 할당할 수 있는지 확인합니다. 자세한 내용은 참조 가이드를 참고하세요. 할당할 수 없는 카테고리에 동영상을 할당하려고 하면 API에서 <code> 태그의 값이 deprecated인 오류 메시지를 반환합니다.

• API 응답에서 <link> 태그를 사용하여 피드의 항목 이전 페이지 또는 다음 페이지의 페이지로 나누기 링크를 식별합니다. 자세한 내용은 참조 가이드의 결과 페이징 섹션을 참고하세요.