Kết nối một provider

Một provider cần một sync token trước khi có thể nói bất cứ điều gì với dịch vụ, và nó nhận token theo cách một chiếc tivi nhận tài khoản: nó hiện một mã, một người duyệt mã đó ở nơi họ đã đăng nhập sẵn, và provider nhận thông tin xác thực của mình. Không có gì phải sao chép, gõ hay dán.

Cách này thay cho việc cho chủ thư viện xem một token để dán vào dòng lệnh. Ứng dụng không còn hiển thị sync token cho bất kỳ ai, nên pairing là cách duy nhất để có được một token.

Luồng

1. Provider xin dịch vụ một pairing, và được cấp một mã (code), một liên kết (link) và một poll secret.
2. Provider mở liên kết trong trình duyệt, hoặc, nếu không có màn hình, in nó ra cùng với mã. Liên kết dùng được trên mọi thiết bị, nên chủ thư viện có thể mở nó trên điện thoại.
3. Trên trang đó, chủ thư viện đăng nhập hoặc tạo tài khoản, đặt tên cho thư viện và duyệt. Trang cho biết thiết bị nào đang xin và hiện mã, để chủ thư viện nhận ra yêu cầu là của mình.
4. Provider thăm dò (poll) bằng poll secret. Lần thăm dò đầu tiên sau khi được duyệt trả về sync token, và không lần nào sau đó trả lại nữa.

Bắt đầu

POST https://api.lets.dj/providers/pair/start
Content-Type: application/json

{ "deviceName": "Ryan’s MacBook" }

Route này không cần thông tin xác thực, vì một provider chưa được ghép nối thì chưa có gì. Nội dung yêu cầu là tùy chọn. deviceName được hiện cho chủ thư viện trên trang duyệt, ngay cạnh mã, nên hãy đặt một cái tên họ sẽ nhận ra. Đây là phép kiểm tra yếu hơn trong hai phép — cái tên là do chính máy đó tự xưng, còn mã là giá trị mà cả hai bên đều giữ độc lập — nhưng nó là thứ cho họ biết máy nào của mình đang xin. Nó bị cắt còn 60 ký tự và các ký tự điều khiển bị thay bằng dấu cách.

{
  "code": "K7QM-X4NP",
  "pollSecret": "…",
  "pairUrl": "https://app.lets.dj/pair?code=K7QM-X4NP",
  "expiresAt": 1790000000000,
  "pollIntervalSeconds": 2
}

• code gồm tám ký tự lấy từ một bảng chữ không có ký tự nào dễ nhầm với ký tự khác (không có 0 hay O, không có 1 hay I hay L), hiển thị thành hai nhóm bốn. Người ta đọc to và gõ lại chúng khi một liên kết không mở được. Nó là cách trang của chủ thư viện tìm ra pairing. Nó không phải thứ bạn dùng để chứng minh mình là ai.
• pollSecret là thứ bạn dùng để chứng minh mình là ai. Hãy giữ kín và chỉ dùng nó để thăm dò.
• pairUrl là liên kết cần mở. Hãy dùng nguyên như được cấp thay vì tự dựng.
• expiresAt là số mili giây tính từ epoch.
• pollIntervalSeconds là khoảng chờ giữa các lần thăm dò.

Một phản hồi 429 kèm "code": "too_many_pairings" và header Retry-After nghĩa là dịch vụ có một giới hạn số pairing đang mở cùng lúc, tồn tại vì đây là route duy nhất ai cũng gọi được. Hãy chờ rồi xin lại.

Kéo dài bao lâu

Một pairing mở trong ba mươi phút kể từ lúc được tạo. Mỗi lần chủ thư viện đến trang duyệt khi đã đăng nhập, đồng hồ được đặt lại, nhưng không bao giờ vượt quá hai giờ kể từ lúc tạo. Khi đã được duyệt, còn thêm ba mươi phút nữa để nhận token.

Sự rộng rãi này là có chủ ý và dành cho người mà việc này sinh ra để phục vụ, người có thể phải tạo tài khoản, chờ email xác minh và tìm nó trong thư rác trước khi duyệt được bất cứ thứ gì. Mười phút là con số đầu tiên, và nó sẽ làm hỏng việc của đúng những người ấy.

Hãy coi các con số này là cách dịch vụ hoạt động hiện nay và dựa vào expiresAt, giá trị mà lần thăm dò trả về và có thể dịch chuyển. Khi một pairing hết hạn, hãy xin cái mới và hiện mã mới. Một provider làm như vậy có thể được để chạy trong lúc ai đó đăng ký.

Thăm dò

POST https://api.lets.dj/providers/pair/poll
Authorization: Bearer <poll secret>

Đây là route duy nhất mà bearer không phải là sync token.

Khi chủ thư viện chưa duyệt:

{ "status": "pending", "expiresAt": 1790000000000 }

Sau khi được duyệt, một lần duy nhất:

{
  "status": "approved",
  "syncToken": "…",
  "bridgeId": "0123456789abcdef",
  "hostname": "0123456789abcdef.letsdj.io",
  "label": "Karaoke at Ryan’s"
}

• syncToken được tạo ra vào đúng lúc phản hồi này được dựng. Dịch vụ chỉ giữ một bản băm của nó và không thể nói lại. Hãy lưu nó trước khi làm bất cứ việc gì khác có thể thất bại. Nếu mất, cách khắc phục duy nhất là ghép nối lại, và ghép nối lại tạo ra một thư viện mới; thư viện cũ bị để trống cho chủ thư viện xóa.
• bridgeId và hostname là tên của thư viện trên tên miền của dịch vụ, mô tả tại Một cái tên và một chứng chỉ. Hãy dùng hostname nguyên như được cấp.
• label là cái tên chủ thư viện đã đặt cho thư viện.

Các phản hồi được đánh dấu Cache-Control: no-store, vì một token bị lưu đệm đâu đó trên đường đi là một token người khác đang giữ.

Các lỗi đều là 4xx kèm một code:

• 410 expired: pairing đã hết hạn. Hãy bắt đầu cái mới.
• 410 already_collected: token đã được giao, có thể cho một lần thăm dò mà bạn chưa bao giờ nhận được câu trả lời. Hãy bắt đầu cái mới.
• 403 unknown_pairing: poll secret không khớp pairing nào. Hãy bắt đầu cái mới.
• 401 missing_token: không có bearer.

Sau khi ghép nối

Thư viện giờ đã tồn tại và đang trống, và trang của chủ thư viện cho biết nó đã được kết nối. Nó trở nên sẵn sàng khi bạn gửi danh mục đầu tiên: xem Gửi danh mục.

Một sync token không hết hạn. Nó ngừng hoạt động khi chủ thư viện xóa thư viện, và từ đó mọi route đều trả 403, là tín hiệu được mô tả trong phần Quy ước.

Đừng dùng chung một sync token cho hai chương trình. Mỗi lần đồng bộ thay thế địa chỉ và media token mà thư viện đang lưu, nên chương trình thứ hai sẽ âm thầm lấy mất thư viện từ chương trình thứ nhất.