Skip to content

Commit 6daf9f6

Browse files
SimonWoolfSimonWoolf
committed
Add docs for update, delete, getMessage, getMessageVersions
1 parent 7021928 commit 6daf9f6

File tree

2 files changed

+83
-0
lines changed

2 files changed

+83
-0
lines changed

‎textile/api-docstrings.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,22 @@ Enables messages to be published and historic messages to be retrieved for a cha
286286
|| `data` ||| The payload of the message. |
287287
| setOptions(options: ChannelOptions) => io ||| RSL7 | Sets the [`ChannelOptions`]{@link ChannelOptions} for the channel. |
288288
|| `options` ||| A [`ChannelOptions`]{@link ChannelOptions} object. |
289+
| getMessage(serialOrMsg: String \| Message) => io Message ||| RSL11 | Retrieves the latest version of a specific message by its serial identifier or by providing a [`Message`]{@link Message} object containing the serial (which will not be mutated). |
290+
|| `serialOrMsg` ||| Either the serial identifier string of the message to retrieve, or a [`Message`]{@link Message} object containing a populated `serial` field. |
291+
||| `Message` || A [`Message`]{@link Message}, the latest version of the message |
292+
| updateMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io Message ||| RSL12 | Publishes an update to existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Note that this publishes an update, it does not mutate the original message if passed in. |
293+
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field and the fields to update. |
294+
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the update operation. |
295+
|| `params` ||| Optional parameters sent as part of the query string. |
296+
||| `Message` || A [`Message`]{@link Message} object containing the updated message. |
297+
| deleteMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io ||| RSL13 | Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object). |
298+
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field. |
299+
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the delete operation. |
300+
|| `params` ||| Optional parameters sent as part of the query string. |
301+
| getMessageVersions(serialOrMsg: String \| Message, params?: `Dict<String, Stringifiable>`) => io `PaginatedResult<Message>` ||| RSL14 | Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. |
302+
|| `serialOrMsg` ||| Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`]{@link Message} object containing a populated `serial` field. |
303+
|| `params` ||| Optional parameters sent as part of the query string. |
304+
||| `PaginatedResult<Message>` || A [`PaginatedResult`]{@link PaginatedResult} object containing an array of [`Message`]{@link Message} objects representing all versions of the message. |
289305
| push: PushChannel ||| RSH4 | A [`PushChannel`]{@link PushChannel} object. |
290306

291307
## class RealtimeChannel
@@ -351,6 +367,22 @@ Enables messages to be published and subscribed to. Also enables historic messag
351367
|| `(Message)` ||| An event listener function. |
352368
| setOptions(options: ChannelOptions) => io ||| RTL16 | Sets the [`ChannelOptions`]{@link ChannelOptions} for the channel. An optional callback may be provided to notify of the success or failure of the operation. |
353369
|| `options` ||| A [`ChannelOptions`]{@link ChannelOptions} object. |
370+
| getMessage(serialOrMsg: String \| Message) => io Message ||| RTL28 | Retrieves the latest version of a specific message by its serial identifier or by providing a [`Message`]{@link Message} object containing the serial. |
371+
|| `serialOrMsg` ||| Either the serial identifier string of the message to retrieve, or a [`Message`]{@link Message} object containing a populated `serial` field. |
372+
||| `Message` || A [`Message`]{@link Message}, the latest version of the message |
373+
| updateMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io Message ||| RTL29 | Updates an existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Note that this publishes an update, it does not mutate the original message if passed in. |
374+
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field and the fields to update. |
375+
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the update operation. |
376+
|| `params` ||| Optional parameters sent as part of the query string. |
377+
||| `Message` || A [`Message`]{@link Message} object containing the updated message. |
378+
| deleteMessage(Message, operation?: MessageOperation, params?: `Dict<String, Stringifiable>`) => io ||| RTL30 | Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object). |
379+
|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field. |
380+
|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the delete operation. |
381+
|| `params` ||| Optional parameters sent as part of the query string. |
382+
| getMessageVersions(serialOrMsg: String \| Message, params?: `Dict<String, Stringifiable>`) => io `PaginatedResult<Message>` ||| RTL31 | Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. |
383+
|| `serialOrMsg` ||| Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`]{@link Message} object containing a populated `serial` field. |
384+
|| `params` ||| Optional parameters sent as part of the query string. |
385+
||| `PaginatedResult<Message>` || A [`PaginatedResult`]{@link PaginatedResult} object containing an array of [`Message`]{@link Message} objects representing all versions of the message. |
354386

355387
## class MessageFilterObject
356388

@@ -364,6 +396,16 @@ Contains properties to filter messages with when calling [`subscribe()`]{@link R
364396
| name: string ||| RTL22a | Filters messages by a specific message `name`. |
365397
| clientId: string ||| RTL22a | Filters messages by a specific message `clientId`. |
366398

399+
## class MessageOperation
400+
401+
Contains metadata about a message update or delete operation.
402+
403+
| Method / Property | Parameter | Returns | Spec | Description |
404+
|---|---|---|---|---|
405+
| clientId?: String ||| MOP2a | Optional identifier of the client performing the operation. |
406+
| description?: String ||| MOP2b | Optional human-readable description of the operation. |
407+
| metadata?: `Dict<String, String>` ||| MOP2c | Optional dictionary of key-value pairs containing additional metadata about the operation. |
408+
367409
## class ChannelProperties
368410

369411
Describes the properties of the channel state.

‎textile/features.textile‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -381,6 +381,38 @@ h3(#rest-channel). RestChannel
381381
* @(RSL8)@ @RestChannel#status@ function: makes a http get request to @<restHost>/channels/<channelId>@ where @<restHost>@ represents the current rest host as described by "@RSC11@":#RSC11
382382
** @(RSL8a)@ Returns a @ChannelDetails@ object
383383
* @(RSL10)@ @RestChannel#annotations@ attribute contains the @RestAnnotations@ object for this channel
384+
* @(RSL11)@ @RestChannel#getMessage@ function:
385+
** @(RSL11a)@ Takes a first argument of a @serial@ string of the message to be retrieved.
386+
*** @(RSL11a1)@ In languages where method overloading is supported, the first argument should also accept a @Message@ object (which must contain a populated @serial@ field)
387+
** @(RSL11b)@ The SDK must send a GET request to the endpoint @/channels/{channelName}/messages/{serial}@
388+
** @(RSL11c)@ Returns the decoded @Message@ object for the specified message serial
389+
* @(RSL12)@ @RestChannel#updateMessage@ function:
390+
** @(RSL12a)@ Takes a first argument of a @Message@ object (which must contain a populated @serial@ field), an optional second argument of a @MessageOperation@ object, and an optional third argument of @Dict<string, stringifiable>@ publish params
391+
** @(RSL12b)@ The SDK must send a PATCH to @/channels/{channelName}/messages/{serial}@, with any @params@ sent in the querystring. The request body consists of an object with the following fields:
392+
*** @(RSL12b1)@ @serial@ - the serial identifier of the message being updated
393+
*** @(RSL12b2)@ @operation@ - the @MessageOperation@ object if provided
394+
*** @(RSL12b3)@ @name@ - the message name from the @Message@ object if provided
395+
*** @(RSL12b4)@ @data@ - the message data from the @Message@ object if provided, encoded per @RSL4@
396+
*** @(RSL12b5)@ @encoding@ - the encoding field set according to @RSL4@ if @data@ was encoded
397+
*** @(RSL12b6)@ @extras@ - the extras field from the @Message@ object if provided
398+
** @(RSL12c)@ The body must be encoded to the appropriate format per @RSC8@
399+
** @(RSL12d)@ Returns the updated @Message@ object, which the server will have responded with
400+
* @(RSL13)@ @RestChannel#deleteMessage@ function:
401+
** @(RSL13a)@ Takes a first argument of a @Message@ object (which must contain a populated @serial@ field), an optional second argument of a @MessageOperation@ object, and an optional third argument of @Dict<string, stringifiable>@ publish params
402+
** @(RSL13b)@ The SDK must send a POST to @/channels/{channelName}/messages/{serial}/delete@, with any @params@ sent in the querystring. The request body consists of an object with the following fields:
403+
*** @(RSL13b1)@ @serial@ - the serial identifier of the message being deleted
404+
*** @(RSL13b2)@ @operation@ - the @MessageOperation@ object if provided
405+
*** @(RSL13b3)@ @name@ - the message name from the @Message@ object if provided
406+
*** @(RSL13b4)@ @data@ - the message data from the @Message@ object if provided, encoded per @RSL4@
407+
*** @(RSL13b5)@ @encoding@ - the encoding field set according to @RSL4@ if @data@ was encoded
408+
*** @(RSL13b6)@ @extras@ - the extras field from the @Message@ object if provided
409+
** @(RSL13c)@ The body must be encoded to the appropriate format per @RSC8@
410+
** @(RSL13d)@ Returns the updated (well, 'deleted') @Message@ object, which the server will have responded with
411+
* @(RSL14)@ @RestChannel#getMessageVersions@ function:
412+
** @(RSL14a)@ Takes a first argument a @serial@ string of the message whose versions are to be retrieved, and an optional second argument of @Dict<string, stringifiable>@ params
413+
*** @(RSL14a1)@ In languages where method overloading is supported, the first argument should also accept a @Message@ object (which must contain a populated @serial@ field)
414+
** @(RSL14b)@ The SDK must send a GET request to the endpoint @/channels/{channelName}/messages/{serial}/versions@
415+
** @(RSL14c)@ Returns a @PaginatedResult<Message>@
384416

385417
h3(#plugins). Plugins
386418
* @(PC1)@ Specific client library features that are not commonly used may be supplied as independent libraries, as plugins, in order to avoid excessively bloating the client library. Although such plugins are packaged as independent libraries, they are still considered logically to be part of the client library code and, as such, may be tightly coupled with the client library implementation. The client library can be assumed to be aware of the plugin specific type and capabilities, and such plugins may by design be coupled to a specific version of the client library.
@@ -820,6 +852,10 @@ h3(#realtime-channel). RealtimeChannel
820852
** @(RTL25a)@ If the channel is already in the given state, calls the listener with a `null` argument.
821853
** @(RTL25b)@ Else, calls @#once@ with the given state and listener.
822854
* @(RTL26)@ @RealtimeChannel#annotations@ attribute contains the @RealtimeAnnotations@ object for this channel
855+
* @(RTL28)@ @RealtimeChannel#getMessage@ function: same as @RestChannel#getMessage@
856+
* @(RTL29)@ @RealtimeChannel#updateMessage@ function: same as @RestChannel#updateMessage@
857+
* @(RTL30)@ @RealtimeChannel#deleteMessage@ function: same as @RestChannel#deleteMessage@
858+
* @(RTL31)@ @RealtimeChannel#getMessageVersions@ function: same as @RestChannel#getMessageVersions@
823859

824860
h3(#realtime-presence). RealtimePresence
825861

@@ -2449,6 +2485,11 @@ class ChannelOptions: // TB*
24492485
params?: Dict<String, String> // TB2c
24502486
modes?: [ChannelMode] // TB2d
24512487

2488+
class MessageOperation: // MOP*
2489+
clientId?: String // MOP2a
2490+
description?: String // MOP2b
2491+
metadata?: Dict<String, String> // MOP2c
2492+
24522493
class DeriveOptions: // DO*
24532494
filter: String // DO2a (The filter string is a valid JMESPath String Expression)
24542495

0 commit comments

Comments
 (0)