이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

각 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 요청에서 지원되지 않는 매개변수를 무시하는 동작으로, 잘못된 요청 매개변수가 포함된 API 요청을 거부하도록 YouTube에 지시합니다.

변경될 수 있는 기능

YouTube는 요청 매개변수를 선택적으로 추가할 수 있습니다.
YouTube는 열거형 값 집합이 있는 기존 매개변수에 새 값을 추가할 수 있습니다.
YouTube는 유효한 매개변수에 잘못된 매개변수 값이 포함된 요청을 거부할 수 있습니다. 따라서 과도하게 관대한 파싱으로 인해 잘못 수락된 요청은 거부될 수 있습니다.
YouTube는 HTTP 요청 헤더를 선택적으로 추가할 수 있습니다.
YouTube는 리소스를 삽입하거나 업데이트할 때 보관 (저장)하는 정보를 변경할 수 있습니다. 그러나 이러한 결정은 해당 API 요청의 구문에 영향을 미치거나 변경을 요구하지 않습니다.
YouTube는 탐색 가능한 카테고리 집합 또는 새로 업로드한 동영상이 할당될 수 있는 카테고리 집합을 변경할 수 있습니다.
문서화되지 않은 기능은 언제든지 삭제하거나 변경할 수 있습니다.

API 응답

변경할 수 없는 기능

기존 XML 태그 이름입니다.
미디어 RSS 사양에 따라 해당 사양에 정의되어 있고 피드 항목에 여러 번 표시되는 요소의 순서를 결정합니다. 예를 들어 항목에 여러 개의 <media:thumbnail> 태그가 있는 경우 중요도에 따라 정렬됩니다.
피드 또는 피드 항목에 설명된 항목의 유형을 식별하는 <category> 태그의 term 속성 값입니다. <feed> 또는 <entry> 태그 내에서 <id> 태그는 항목으로 식별되는 고유 리소스를 지정하고 <category> 태그는 항목에서 설명하는 리소스의 종류를 식별합니다. 이 <category> 태그의 경우 스킴 속성 값은 http://schemas.google.com/g/2005#kind이고 용어 속성 값은 피드 항목이 동영상, 재생목록 링크, 구독, 연락처 또는 다른 항목 유형을 설명하는지를 나타냅니다.

변경될 수 있는 기능

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 응답에는 YouTube 웹사이트의 리소스에 연결되는 식별자(예: 동영상 ID(<yt:videoid>) 및 사용자 이름(<name>, <media:credit>).))에 대한 특정 태그가 포함됩니다.
정보를 삽입 (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> 태그를 사용하여 피드 항목의 이전 페이지 또는 다음 페이지의 페이지로 나누기 링크를 식별합니다. 자세한 내용은 참조 가이드의 결과를 통해 페이지 나누기 섹션을 참조하세요.