-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathnotifications.apib
154 lines (98 loc) · 5.77 KB
/
notifications.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
FORMAT: 1A
HOST: https://api.thegrid.io/
# Group Registering for Notifications
Notifications allow applications to instantly know when certain data has changed,
or certain user actions has been performed. Correct implementation of notifications
allows user to use multiple devices, with the data always being up-to-date.
To receive notifications, the Grid app needs to be registered as a client application.
The notifications sent to clients follow the [notifications schema](schema/notification.json).
For how to deal with particular notifications, see the recommendations found below.
When reacting to an action the client needs to make the request using the regular Bearer token.
## User clients [/client]
### List user's active client apps [GET]
+ Response 200 (application/json)
+ Body
```
[
<!-- include(examples/client-gcm.json) -->
<!-- include(examples/client-apn_production.json) -->
]
```
### Register a new client app [POST]
+ Request (application/json)
+ Body
```
<!-- include(examples/client-gcm.json) -->
```
+ Schema
```
<!-- include(schema/client.json) -->
```
+ Response 201
+ Headers
Location: /client/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177
## Client app [/client/{id}]
+ Parameters
+ id (required, string) - Site UUID
### Remove a client app [DELETE]
+ Response 204
## Notifications testing [/molly/repeat]
### Send a test notification [POST]
For development purposes, you can make Molly talk to you over the registered notification channels (like Google Cloud Messaging).
A push message will be sent to the user's all registered clients.
+ Request (application/json)
+ Schema
```
<!-- include(schema/notification.json) -->
```
+ Response 202
# Group Available Notifications
## Synchronization
These notification payloads are intended for API clients to refresh changed data from the server. They are not indended to be visualized except for possible data changes in the UI (new items appearing, site configs changing, etc).
User events:
* `user_merge`: user account has been merged with another one. All data should be re-fetched
* `user_removed`: the user account has been disabled. Remove data and disable application usage
* `user_activated`: the authenticated user's account has been activated. Re-fetch data and enable full application usage. This one may be worthy of notifying user visually
Item events:
* `new_item`: new item has been created, fetch with `id`
* `updated_item`: item has been updated, fetch with `id`
* `published_item`: item has been published to `sites`, update display accordingly. Fetch with `id` if needed
* `unpublished_item`: item has been unpublished from `sites`, update display accordingly. Fetch with `id` if needed
* `removed_item`: item has been deleted. Remove from app
Site events:
* `new_site`: new site has been created, fetch with `id` or use `repo`
* `updated_site`: site has been updated, fetch with `id` or use `repo`. These can be also caused by site publishing process
* `removed_site`: site has been deleted. Remove from app
Redesign events:
* `started_redesign`: new redesign is being worked on, available from listing with `?inflight=true`
* `new_redesign`: new redesign is available for the site, fetch with `id`
* `updated_redesign`: redesign has been updated (usually with a rating), fetch with `id`
* `removed_redesign`: redesign has been removed. Remove from app
## Job status
The job status notifications are related to long-running operations initiated by the user or a back-end process that the user should be aware of. These should be shown with persistent progress indicators either in the system's notifications are or in the context of the action made (for example, a "loading" item card).
Job events contain the following information:
* `job_id`: identifier for the long-running job, can be used for polling the job endpoint
* `item`: item ID associated with the job, if any
* `job_type`: type of the job, currently either `share` or `publish`
Job status changes cause the following events to be sent:
* `started_job`: job has started. Show progress notification accordingly
* `updated_job`: there has been progress on the job. Possibly move progress indicator one step forward
* `failed_job`: job has failed. Replace progress notification with a failure indicator
* `completed_job`: job has completed. Remove progress notification or replace with a success indicator
## Actionable notifications
These notifications are related to something urgent the user should be able to react to. They should be shown as OS-level notifications that may have additional information like screenshots or action buttons associated with them.
Notifications from the `molly` AI:
These notifications are meant to be shown visually, and contain the texts written by the AI to the user. In general, they have the `molly` collapse key if available on the platform.
Molly notifications contain the following keys:
* `type`: subtype of the notification, for example `review` or `publish`
* `title`: textual title for the notification
* `text`: full notification text
* `url`: URL that the user can visit to see more related to the notification, for example a newly redesigned website of theirs
* `preview`: Screenshot for the URL above, if any
* `ipfs`: IPFS hash for the URL, if any
* `site`: ID of the site associated with the notification
* `job`: ID of the job associated with the notification, if any. Can be used to morph job progress to visual notification
* `actions`: array of potential additional actions that user can perform, each containing `label`, `icon`, `path`, `method`, and `payload`
Molly notification types:
* `review`: The AI has multiple designs for the user to review and choose from
* `publish`: A new version of the site or some pages within is now live