Nguyên tắc tương thích ngược

Mỗi yêu cầu API dữ liệu YouTube có thể chỉ định phiên bản API mà YouTube sẽ sử dụng để xử lý yêu cầu đó. Nếu một yêu cầu không chỉ định phiên bản API, thì YouTube sẽ sử dụng phiên bản API được hỗ trợ cũ nhất để xử lý yêu cầu đó. Phiên bản được hỗ trợ cũ nhất hiện là 1. Xin lưu ý các đặc điểm sau của số phiên bản API:

  • YouTube có thể phát hành bản cập nhật cho một phiên bản API cụ thể mà bản phát hành này chưa được gán số phiên bản mới. Những bản cập nhật có khả năng tương thích ngược này có thể bao gồm các tính năng API không bắt buộc, bản sửa lỗi hoặc cả hai.

  • Số gia phiên bản API tăng lên xác định một bản phát hành chứa các thay đổi không tương thích với các phiên bản API trước.

Tài liệu này xác định nguyên tắc về khả năng tương thích ngược để cập nhật vào phiên bản API cụ thể, mục đầu tiên được liệt kê ở trên. Nguyên tắc này nhằm phân biệt các loại chức năng API sau:

  • Các nguyên tắc này xác định chức năng API có thể thay đổi ngay cả khi bạn không sửa đổi phiên bản API để xử lý yêu cầu API. Mã của bạn sẽ xử lý những thay đổi này mà không bị hỏng. Ví dụ: nếu YouTube thêm thẻ XML mới vào phản hồi API, thì mã của bạn nên bỏ qua những thẻ đó.

  • Nguyên tắc này cũng quy định chức năng của API mà YouTube không có ý định thay đổi khi cập nhật một phiên bản API cụ thể. Nói cách khác, bạn chỉ nên mong đợi chức năng thay đổi nếu YouTube phát hành một phiên bản API mới và mã của bạn không cần phải tìm cách xử lý những loại thay đổi này.

Giới thiệu về tài liệu này

Tài liệu này có các mục sau:

  • Phần Yêu cầu API xác định các nguyên tắc về khả năng tương thích ngược liên quan đến tiêu đề yêu cầu HTTP, tham số yêu cầu API, tên phần tử XML (khi chúng xuất hiện trong các yêu cầu API) và các yêu cầu API được định dạng không đúng cách.

  • Phần Phản hồi API xác định nguyên tắc về khả năng tương thích ngược liên quan đến tên phần tử XML (như xuất hiện trong các phản hồi API) và thứ tự các thẻ và thuộc tính XML xuất hiện trong phản hồi API.

  • Phần Các phương pháp hay nhất trình bày các đề xuất tích hợp API YouTube với ứng dụng.

Yêu cầu API

Chức năng không nhằm thay đổi

  • Các tham số yêu cầu hiện có.

  • Các giá trị thông số hiện có cho các thông số có giá trị được liệt kê hoặc ý nghĩa của các giá trị thông số đó.

  • Tên của các phần tử XML được dùng trong yêu cầu POST (chèn) API hoặc yêu cầu PUT (cập nhật).

  • Tập hợp tiêu đề của yêu cầu HTTP cần thiết cho từng loại yêu cầu API. Nguyên tắc này có nghĩa là YouTube không có ý định thêm tiêu đề của yêu cầu HTTP bắt buộc hay thay đổi các tiêu đề của yêu cầu không bắt buộc hiện có.

  • Hành vi bỏ qua các tham số không được hỗ trợ trong một yêu cầu API trừ khi yêu cầu đó sử dụng tham số strict để hướng dẫn YouTube từ chối một yêu cầu API chứa các tham số yêu cầu không hợp lệ.

Chức năng có thể thay đổi

  • YouTube có thể thêm các thông số yêu cầu không bắt buộc.

  • YouTube có thể thêm giá trị mới cho các tham số hiện có có các nhóm giá trị được liệt kê.

  • YouTube có thể từ chối bất kỳ yêu cầu nào mà trong đó các tham số hợp lệ chứa giá trị tham số không hợp lệ. Kết quả là các yêu cầu được định dạng không đúng đã được chấp nhận do phân tích cú pháp quá thoải mái có thể bị từ chối nếu logic phân tích cú pháp đã được sửa.

  • YouTube có thể thêm tiêu đề của yêu cầu HTTP (không bắt buộc).

  • YouTube có thể thay đổi thông tin được giữ lại (lưu trữ) khi chèn hoặc cập nhật tài nguyên. Tuy nhiên, quyết định đó sẽ không ảnh hưởng hoặc yêu cầu thay đổi cú pháp của các yêu cầu API tương ứng.

  • YouTube có thể thay đổi nhóm danh mục có thể duyệt xem hoặc nhóm danh mục mà bạn có thể chỉ định video mới tải lên.

  • Chức năng không được ghi nhận có thể bị xoá hoặc thay đổi bất cứ lúc nào.

phản hồi của API

Chức năng không nhằm thay đổi

  • Tên thẻ XML hiện tại.

  • Tuân theo thông số kỹ thuật của RSS cho nội dung đa phương tiện để xác định thứ tự của các phần tử được xác định trong quy cách đó và xuất hiện nhiều lần trong một mục nguồn cấp dữ liệu. Ví dụ: nếu một mục chứa nhiều thẻ <media:thumbnail>, thì các thẻ này được sắp xếp theo mức độ quan trọng.

  • Giá trị thuộc tính term của thẻ <category> giúp xác định loại mặt hàng được mô tả trong nguồn cấp dữ liệu hoặc mục nhập nguồn cấp dữ liệu. Trong thẻ <feed> hoặc <entry>, thẻ <id> chỉ định tài nguyên riêng biệt do mục nhập xác định và thẻ <category> xác định loại tài nguyên do mục nhập mô tả. Đối với thẻ <category> này, giá trị của thuộc tính lược đồ là http://schemas.google.com/g/2005#kind và giá trị của thuộc tính cụm từ cho biết các mục trong nguồn cấp dữ liệu có mô tả video, đường liên kết đến danh sách phát, kênh đăng ký, danh bạ hay một loại thực thể khác không.

Chức năng có thể thay đổi

  • YouTube có thể thêm thẻ XML mới vào phản hồi của API.

  • YouTube có thể thêm các thuộc tính mới vào các thẻ XML hiện có.

  • Bạn có thể lặp lại các thẻ API hiện có bằng nhiều giá trị. Ví dụ: YouTube có thể thêm một thẻ <media:restriction> mới có giá trị type khác hoặc một thẻ <media:credit> mới có scheme và role khác.

  • Thứ tự của các thẻ XML và thuộc tính trong phản hồi API có thể thay đổi.

  • Bạn có thể xoá các thẻ con không bắt buộc khỏi phản hồi của API.

  • Chức năng không được ghi nhận có thể bị xoá hoặc thay đổi bất cứ lúc nào.

Các phương pháp hay nhất

  • Sử dụng giá trị thẻ <id> để xác định một mục nhập.

  • Sử dụng đường liên kết self để truy xuất mục nhập.

  • Hãy dùng đường liên kết edit để chỉnh sửa hoặc cập nhật một mục.

  • Sử dụng giá trị thẻ <yt:videoid> cho một mục video để nhận giá trị mà YouTube sử dụng để nhận dạng duy nhất video đó. Không phân tích cú pháp mã video trong một đường liên kết.

  • Hãy dùng các URL được xác định trong thẻ <link>, <content> và <gd:feedLink> để di chuyển giữa các nguồn cấp dữ liệu. YouTube hỗ trợ một tập hợp URL có giới hạn mà bạn có thể xây dựng một cách đáng tin cậy để truy xuất nguồn cấp dữ liệu cụ thể. Ngoài những URL của nguồn cấp dữ liệu được liệt kê dưới đây, bạn không nên tạo URL nguồn cấp dữ liệu của riêng mình vì chúng có thể ngừng hoạt động đột ngột.

    • /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 (xem hướng dẫn tham khảo để biết thêm thông tin)

  • Đừng cố gắng phân tích cú pháp giá trị nhận dạng dạng số hoặc chữ số từ các URL trong phản hồi API. Phản hồi API bao gồm các thẻ cụ thể cho các giá trị nhận dạng liên kết đến các tài nguyên trên trang web YouTube, chẳng hạn như mã video (<yt:videoid>) và tên người dùng (<name> và <media:credit>).

  • Nếu bạn gửi yêu cầu API để chèn (POST) hoặc cập nhật thông tin (PUT), hãy sử dụng phản hồi XML cho yêu cầu đó để xác định giá trị thẻ nào trong yêu cầu thực sự được YouTube lưu trữ. Như đã nêu trong nguyên tắc về khả năng tương thích ngược cho các yêu cầu API, YouTube có thể thay đổi thông tin mà họ giữ lại (lưu trữ) khi chèn hoặc cập nhật tài nguyên, tức là một số thẻ trong yêu cầu có thể bị bỏ qua.

  • Khi bạn truy xuất nguồn cấp dữ liệu XML, hãy lưu trữ các thẻ và thuộc tính XML không được công nhận liên quan đến mục nhập nguồn cấp dữ liệu nếu ứng dụng của bạn cho phép người dùng cập nhật mục nhập đó. Nếu người dùng cập nhật tài nguyên, thì ứng dụng của bạn phải bao gồm mọi thẻ và thuộc tính không nhận dạng được trong yêu cầu cập nhật. Phương pháp này đảm bảo rằng ứng dụng của bạn không vô tình xóa thông tin liên quan đến các tính năng của API mới trong quá trình cập nhật tài nguyên.

    Ví dụ sau minh hoạ phương pháp hay nhất này:

    1. Ứng dụng cho phép người dùng cập nhật nội dung mô tả video.
    2. Ứng dụng của bạn truy xuất mục video bằng API nhưng không nhận ra một trong các thẻ trong mục đó.
    3. Người dùng sửa đổi nội dung mô tả video.
    4. Ứng dụng của bạn cần gửi một mục video hoàn chỉnh đến API. Mục nhập cần bao gồm thẻ không được công nhận từ bước 2; nếu không, giá trị đó có thể bị xóa.

  • Xác nhận rằng một thẻ tồn tại và chứa giá trị không rỗng trước khi cố gắng hiển thị giá trị thẻ.

  • Như đã lưu ý ở trên, YouTube có thể thêm giá trị mới cho các thẻ hoặc thuộc tính hiện có có các nhóm giá trị được liệt kê. Theo quy tắc, mã của bạn phải phân tích cú pháp các giá trị của các phần tử XML đã liệt kê tập hợp giá trị và sau đó xác định các hành động phù hợp với các giá trị đó. Phương pháp này được đề xuất ngay cả khi chỉ có một giá trị được liệt kê cho phần tử.

    Ví dụ: thẻ <media:credit> xác định chủ sở hữu của video. Giá trị ghi lại duy nhất cho thuộc tính role của thẻ là uploader, cho biết video do một đối tác YouTube tải lên. Phương pháp hay nhất này quy định rằng ứng dụng phải xác nhận rằng giá trị của thuộc tính role của thẻ thực sự là uploader trước khi xác định người dùng tương ứng làm chủ sở hữu video. (Việc này giúp đảm bảo mã của bạn không xác định sai chủ sở hữu video nếu YouTube thêm các loại ghi nhận quyền tác giả khác (ví dụ: đạo diễn) cho video.)

    • Nếu một thẻ có một tập hợp giá trị được liệt kê và bạn không nhận ra giá trị của thẻ đó, thì bạn nên bỏ qua toàn bộ <entry> trong đó thẻ xuất hiện.

    • Bỏ qua mục nhập nguồn cấp dữ liệu gói thuê bao nếu bạn không nhận ra giá trị của thuộc tính term cho thẻ <category> có giá trị thuộc tính scheme là http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Thẻ cụ thể đó xác định loại gói thuê bao do mục nhập xác định. Nếu không nhận ra loại gói thuê bao, ứng dụng của bạn sẽ không hiển thị thông tin về mục nhập đó.

    • Nếu có bất kỳ thuộc tính nào khác có tập hợp giá trị được liệt kê và bạn không nhận ra giá trị của thuộc tính đó thì bạn nên bỏ qua thẻ mà thuộc tính xuất hiện.

  • Mã xử lý ứng dụng của bạn sẽ nhận được thông báo yt:error bất cứ lúc nào. Trong trường hợp không thực hiện được thao tác API, ứng dụng của bạn sẽ xác định lỗi và hiển thị một thông báo có ý nghĩa cho người dùng.

  • YouTube có thể thêm các danh mục mới để phân loại video bất cứ lúc nào. YouTube cũng có thể cập nhật hoặc ngừng sử dụng các danh mục hiện có. Bạn có thể truy xuất tệp danh mục hiện tại từ http://gdata.youtube.com/schemas/2007/categories.cat.

    • Nếu ứng dụng của bạn cho phép người dùng duyệt qua video theo danh mục hoặc tải lên video, hãy truy xuất tệp danh mục được cập nhật hằng tuần.

    • Nếu ứng dụng của bạn cho phép người dùng duyệt qua video theo danh mục, hãy truy xuất cả tệp danh mục cập nhật nếu API trả về nguồn cấp dữ liệu trống để phản hồi lượt tìm kiếm danh mục.

    • Nếu ứng dụng của bạn cho phép người dùng tải video lên, hãy truy xuất cả tệp danh mục cập nhật trước khi tải video lên và xác nhận rằng danh mục liên kết với video đã tải lên vẫn có thể chỉ định. Xem hướng dẫn tham khảo để biết thêm thông tin. (Xin lưu ý rằng nếu bạn cố gắng chỉ định video cho một danh mục không thể gán được, API sẽ trả về một thông báo lỗi với giá trị của thẻ <code> là deprecated.)

  • Dùng các thẻ <link> trong phản hồi API để xác định các đường liên kết phân trang cho mục nhập trước đó và/hoặc tiếp theo trong một nguồn cấp dữ liệu. Xem phần Phân trang thông qua kết quả của hướng dẫn tham khảo để biết thêm thông tin.