summaryrefslogtreecommitdiffstats
path: root/testing/web-platform/tests/tools/wave/docs/rest-api/sessions-api/events.md
blob: c1b693c88c59211efd303baade5949e42a015c60 (plain)
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
# `events` - [Sessions API](../README.md#sessions-api)

Session events can be used to send messages related to a specific session for
others to receive. This can include status updates or action that running
session react on.

For possible events see [Session Event Types](./event-types.md)

## 1. `listen events`

Listen for session specific events by registering on the `events` endpoint using HTTP long polling.

### HTTP Request

```
GET /api/sessions/<token>/events
```

### Query Parameters

| Parameter    | Desciption                                                                                                                                                                                       | Default | Example        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------------- |
| `last_event` | The number of the last received event. All events that are newer than `last_event` are returned immediately. If there are no newer events, connection stays open until a new event is triggered. | None    | `last_event=5` |

#### Response Payload

```json
[
  {
    "type": "String",
    "data": "String",
    "number": "Number"
  },
  ...
]
```

- **type**: the type of event that occurred.
- **data**: the actual payload of the event
- **number**: the number of the event

#### Example

```
GET /api/sessions/6fdbd1a0-c339-11e9-b775-6d49dd567772/events?last_event=8
```

```json
[
  {
    "type": "status",
    "data": "paused",
    "number": 9
  },
  {
    "type": "status",
    "data": "running",
    "number": 10
  },
  {
    "type": "status",
    "data": "paused",
    "number": 11
  },
  {
    "type": "status",
    "data": "running",
    "number": 12
  }
]
```

## 2. `push events`

Push session specific events for any registered listeners to receive.

### HTTP Request

```
POST /api/sessions/<token>/events
```

```json
{
  "type": "String",
  "data": "String"
}
```

- **type**: the type of event that occurred.
- **data**: the actual payload of the event

#### Example

```
POST /api/sessions/6fdbd1a0-c339-11e9-b775-6d49dd567772/events
```

```json
{
  "type": "status",
  "data": "paused"
}
```