[AIT-468] Add specification for the LiveObjects REST API#476
Open
VeskeR wants to merge 1 commit into
Open
Conversation
The REST counterpart of LiveObjects shipped in ably-js in [1]. This spec PR adds an RSO* section under objects-features so other SDKs have a contract to implement against. Decisions worth recording: - Same Objects plugin, both transports. Rather than introducing a separate PluginType for REST, PC5 now covers both RealtimeObjects and RestObject. This matches the ably-js packaging and keeps a single plugin concept for users. - RestObjectOperation as a flat discriminated union. Common targeting fields plus exactly-one body field, mirroring the wire format and the existing "set exactly one field" patterns (OD2, OOP3, PublishObjectData). A class hierarchy was considered but rejected: consistency with the rest of the Objects spec and the 1:1 mapping to the wire format won, and languages without sum types (Go, Python, PHP) gain little from inheritance either. - Paths are opaque to the SDK. RSO6 explicitly forbids client-side parsing or normalization. Path syntax (wildcards, escaping) is server-defined and can evolve without coupling SDK releases to it. - Full-mode leaves reuse ObjectData. Rather than introducing a parallel RestObjectData type, RSO9c defers to OD5 with explicit guarantees about which fields are unset post-decode. Avoids type duplication. - Client-side object IDs via generateObjectId. Realtime always generates IDs locally (RTO14); REST normally delegates to the server but supports local generation for batches where one operation needs to reference another newly-created object by ID. RSO5j documents this asymmetry so implementers understand why both Create and CreateWithObjectId variants exist. [1] ably/ably-js#2109
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cross-checked against Paddy's proposal at #475 (commit 13be81c), with addressed open questsions.
The REST counterpart of LiveObjects shipped in ably-js in [1]. This spec PR adds an RSO* section under objects-features so other SDKs have a contract to implement against.
Decisions worth recording:
Same Objects plugin, both transports. Rather than introducing a separate PluginType for REST, PC5 now covers both RealtimeObjects and RestObject. This matches the ably-js packaging and keeps a single plugin concept for users.
RestObjectOperation as a flat discriminated union. Common targeting fields plus exactly-one body field, mirroring the wire format and the existing "set exactly one field" patterns (OD2, OOP3, PublishObjectData). A class hierarchy was considered but rejected: consistency with the rest of the Objects spec and the 1:1 mapping to the wire format won, and languages without sum types (Go, Python, PHP) gain little from inheritance either.
Paths are opaque to the SDK. RSO6 explicitly forbids client-side parsing or normalization. Path syntax (wildcards, escaping) is server-defined and can evolve without coupling SDK releases to it.
Full-mode leaves reuse ObjectData. Rather than introducing a parallel RestObjectData type, RSO9c defers to OD5 with explicit guarantees about which fields are unset post-decode. Avoids type duplication.
Client-side object IDs via generateObjectId. Realtime always generates IDs locally (RTO14); REST normally delegates to the server but supports local generation for batches where one operation needs to reference another newly-created object by ID. RSO5j documents this asymmetry so implementers understand why both Create and CreateWithObjectId variants exist.
[1] ably/ably-js#2109
Resolves AIT-468