Nguyên tắc về khả năng tương thích ngược

Mỗi yêu cầu YouTube Data API 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ũ nhất được hỗ trợ để xử lý yêu cầu đó. Phiên bản cũ nhất được hỗ trợ hiện là 1. Xin lưu ý các đặc điểm sau đây 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 không được chỉ định số phiên bản mới. Các bản cập nhật 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ố phiên bản API tăng dầ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 các nguyên tắc về khả năng tương thích ngược cho các bản cập nhật đối với một 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 giữa các loại chức năng API sau:

  • 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 cần dùng để xử lý các yêu cầu API. Mã của bạn phải xử lý các thay đổi này mà không bị lỗi. Ví dụ: nếu YouTube thêm các thẻ XML mới vào phản hồi API, thì mã của bạn sẽ bỏ qua các thẻ đó.

  • Nguyên tắc này cũng xác định chức năng 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 dự kiến chức năng đó thay đổi nếu YouTube phát hành phiên bản API mới và mã của bạn không cần phải cố gắng xử lý những loại thay đổi này.

Thông tin về tài liệu này

Tài liệu này bao gồm các phần sau:

  • Mục 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 (như xuất hiện trong yêu cầu API) và yêu cầu API được tạo không đúng cách.

  • Mục Phản hồi API xác định các 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 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 khách của bạn.

Yêu cầu API

Chức năng không được thay đổi

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

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

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

  • Bộ tiêu đề yêu cầu HTTP bắt buộc 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 đề yêu cầu HTTP bắt buộc hoặc thay đổi tiêu đề yêu cầu không bắt buộc hiện có thành tiêu đề bắt buộc.

  • Hành vi bỏ qua các tham số không được hỗ trợ trong yêu cầu API, trừ phi yêu cầu đó sử dụng tham số strict. Tham số này sẽ hướng dẫn YouTube từ chối 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 các giá trị mới cho các thông số hiện có có tập hợp giá trị được liệt kê.

  • YouTube có thể từ chối mọi yêu cầu mà trong đó các thông số hợp lệ chứa giá trị thông số không hợp lệ. Do đó, các yêu cầu được chấp nhận do quá trình phân tích cú pháp quá nới lỏng nhưng được tạo không đúng cách có thể bị từ chối nếu logic phân tích cú pháp được sửa.

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

  • YouTube có thể thay đổi thông tin mà YouTube 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 như vậy 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ể xem hoặc nhóm danh mục mà video mới tải lên có thể được chỉ định.

  • Chức năng chưa đượ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 được thay đổi

  • Tên thẻ XML hiện có.

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

  • Giá trị thuộc tính term của thẻ <category> xác định loại mục đượ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 duy nhấ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 giao thức là http://schemas.google.com/g/2005#kind và giá trị của thuộc tính thuật ngữ cho biết các mục trong nguồn cấp dữ liệu mô tả video, đường liên kết đến danh sách phát, gói thuê bao, thông tin liên hệ hay một loại thực thể khác.

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

  • YouTube có thể thêm các thẻ XML mới vào phản hồi 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ó với các giá trị khác nhau. 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ẻ và thuộc tính XML trong phản hồi API có thể thay đổi.

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

  • Chức năng chưa đượ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ột mục nhập.

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

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

  • Sử 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 số URL mà bạn có thể tạo một cách đáng tin cậy để truy xuất các nguồn cấp dữ liệu cụ thể. Ngoài các URL nguồn cấp dữ liệu được liệt kê bên dưới, bạn không nên tạo URL nguồn cấp dữ liệu của riêng mình vì các URL đó có thể ngừng hoạt động một cách độ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ố và chữ cái từ URL trong phản hồi API. Phản hồi API bao gồm các thẻ cụ thể cho giá trị nhận dạng liên kết đến 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 (PUT) thông tin, 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 mà YouTube thực sự lưu trữ. Như đã nêu trong nguyên tắc về khả năng tương thích ngược cho yêu cầu API, YouTube có thể thay đổi thông tin mà YouTube giữ lại (lưu trữ) khi chèn hoặc cập nhật tài nguyên. Điều này có nghĩa 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 nhận dạng liên quan đến một 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 đưa mọi thẻ và thuộc tính không được nhận dạng vào 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 xoá thông tin liên quan đến các tính năng API mới trong quá trình cập nhật tài nguyên.

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

    1. Ứng dụng của bạn 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 dạng được 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 trở lại API. Mục nhập cần bao gồm thẻ không được nhận dạng ở bước 2; nếu không, giá trị đó có thể bị xoá.

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

  • Như đã lưu ý ở trên, YouTube có thể thêm các giá trị mới cho các thẻ hoặc thuộc tính hiện có có tập hợp 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 phần tử XML có các tập hợp giá trị được liệt kê, sau đó xác định các hành động phù hợp với các giá trị đó. Bạn nên thực hiện phương pháp này ngay cả khi chỉ có một giá trị có thể được liệt kê cho phần tử.

    Ví dụ: thẻ <media:credit> xác định chủ sở hữu của một video. Giá trị duy nhất được ghi nhận cho thuộc tính role của thẻ là uploader, cho biết video do đối tác YouTube tải lên. Phương pháp hay nhất này quy định rằng ứng dụng của bạn 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à chủ sở hữu video. (Biện pháp phòng ngừa này đảm bảo rằng mã của bạn không xác định không chính xác chủ sở hữu video nếu YouTube thêm các loại thông tin khác (ví dụ: đạo diễn) cho một 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> mà thẻ đó xuất hiện.

    • Bỏ qua mục trong 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 xác định. Nếu không nhận dạng được loại gói thuê bao, thì ứng dụng của bạn sẽ không hiển thị thông tin về mục đó.

    • Nếu bất kỳ thuộc tính nào khác 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 thuộc tính đó, thì bạn nên bỏ qua thẻ mà thuộc tính đó xuất hiện.

  • Mã ứng dụng của bạn phải chờ một thông báo yt:error bất cứ lúc nào. Trong trường hợp một thao tác API không thành công, ứng dụng của bạn phải 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 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 xem video theo danh mục hoặc tải video lên, hãy truy xuất tệp danh mụ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 xem video theo danh mục, hãy truy xuất tệp danh mục đã cập nhật nếu API trả về nguồn cấp dữ liệu trống khi tìm kiếm theo 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 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 được liên kết với video đã tải lên vẫn có thể chỉ định được. Hãy 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 một video cho một danh mục không thể chỉ định, thì API sẽ trả về một thông báo lỗi có giá trị của thẻ <code> là deprecated.)

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