Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
dev:web_api:v3:streaming_api [2022/06/23 15:52] – created dstillman | dev:web_api:v3:streaming_api [2023/04/11 17:46] (current) – [Create an empty WebSocket stream] dstillman | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Zotero Streaming API ====== | ====== Zotero Streaming API ====== | ||
- | WIP | + | The Zotero streaming API provides push-based notifications via WebSockets for Zotero library changes, allowing for nearly instantaneous updates when data changes in a library or when a user joins or leaves a library. |
+ | |||
+ | Note that this API provides library-level notifications of changes. It does not provide updated data directly. API consumers that receive notification of a library change should use their standard [[syncing|sync process]] to retrieve data, ensuring a single, consistent code path for both manual and automatic syncing. | ||
+ | |||
+ | To avoid missed updates, clients should connect to the streaming API and then, once connected, trigger a standard sync operation to bring themselves up to date with the current version of a library. | ||
+ | ===== Requests ===== | ||
+ | |||
+ | ==== Create an empty WebSocket stream ==== | ||
+ | |||
+ | <code javascript> | ||
+ | |||
+ | Server response: | ||
+ | |||
+ | < | ||
+ | {" | ||
+ | </ | ||
+ | |||
+ | ==== Add subscriptions to the event stream ==== | ||
+ | |||
+ | Client message: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | "/ | ||
+ | "/ | ||
+ | "/ | ||
+ | ] | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | "/ | ||
+ | "/ | ||
+ | ] | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Server Response: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | "/ | ||
+ | "/ | ||
+ | ] | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | "/ | ||
+ | ] | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | "/ | ||
+ | ] | ||
+ | } | ||
+ | ], | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | All topic subscriptions — new and existing — for the specified API keys are included in the response. Subscriptions for previously added API keys not in the current request are not included. Subscriptions for public topics can be made without specifying an API key, and the newly added topics will be grouped together in the response. | ||
+ | |||
+ | If a '' | ||
+ | |||
+ | Topic subscriptions cannot be removed via '' | ||
+ | |||
+ | === Errors === | ||
+ | |||
+ | | 4413 Request Entity Too Large | Number of subscriptions (including existing subscriptions) would exceed the per-connection limit | | ||
+ | |||
+ | ==== Receive events on the existing event stream ==== | ||
+ | |||
+ | <code javascript> | ||
+ | {" | ||
+ | |||
+ | {" | ||
+ | |||
+ | {" | ||
+ | </ | ||
+ | |||
+ | |||
+ | ==== Delete all subscriptions for a given API key ==== | ||
+ | |||
+ | Client message: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Server response: | ||
+ | |||
+ | < | ||
+ | { | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === Errors === | ||
+ | |4409 Conflict | Subscription with a given API key or topic doesn' | ||
+ | |||
+ | ==== Delete specific API key/topic pair ==== | ||
+ | |||
+ | Client message: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Server response: | ||
+ | |||
+ | < | ||
+ | { | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | If a topic is manually removed from a key that is automatically tracking topics, the resulting list of topics will be fixed and the key will no longer receive '' | ||
+ | |||
+ | === Errors === | ||
+ | | 4409 Conflict | Subscription with the given API key and/or topic doesn' | ||
+ | |||
+ | |||
+ | ==== Delete a public topic subscription ==== | ||
+ | |||
+ | Client message: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Server response: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === Errors === | ||
+ | | 4409 Conflict | Public subscription for the given topic doesn' | ||
+ | |||
+ | ===== Key Access Tracking ===== | ||
+ | |||
+ | For API keys without specified topics, the connection will track the key's access and receive events for all topics available to the key. | ||
+ | |||
+ | For example, if the owner of the key joins a group and the key has access to all of the user's groups, the connection will receive a '' |