0
# HTTP REST API
1

2
The Selenium Grid server exposes comprehensive REST API endpoints for WebDriver protocol implementation, session management, node registration, and Grid administration.
3

4
## Capabilities
5

6
### Router Endpoints
7

8
Router component handles WebDriver protocol endpoints and routes requests to appropriate nodes based on session ID.
9

10
```java { .api }
11
// WebDriver session creation
12
POST /session
13
Content-Type: application/json
14
{
15
  "capabilities": {
16
    "alwaysMatch": { "browserName": "chrome" },
17
    "firstMatch": [{}]
18
  }
19
}
20

21
// WebDriver commands routing
22
GET    /session/{sessionId}/url          // Get current URL
23
POST   /session/{sessionId}/url          // Navigate to URL
24
GET    /session/{sessionId}/title        // Get page title
25
POST   /session/{sessionId}/element      // Find element
26
DELETE /session/{sessionId}              // Delete session
27
```
28

29
All standard W3C WebDriver endpoints are supported and automatically routed to the correct node based on session ownership.
30

31
### Session Map Endpoints
32

33
Session map manages the mapping between session IDs and their corresponding node URIs.
34

35
```java { .api }
36
// Register session with session map
37
POST /se/grid/session/{sessionId}
38
Content-Type: application/json
39
{
40
  "sessionId": "string",
41
  "uri": "http://node-host:port"
42
}
43

44
// Retrieve session URI
45
GET /se/grid/session/{sessionId}
46
Response: {
47
  "sessionId": "string", 
48
  "uri": "http://node-host:port"
49
}
50

51
// Remove session from map
52
DELETE /se/grid/session/{sessionId}
53
Response: HTTP 200 OK
54
```
55

56
### Distributor Endpoints
57

58
Distributor manages node registration and routes new session requests to available nodes.
59

60
```java { .api }
61
// Create new session (WebDriver standard)
62
POST /session
63
Content-Type: application/json
64
{
65
  "capabilities": {
66
    "alwaysMatch": { "browserName": "firefox" },
67
    "firstMatch": [{}]
68
  }
69
}
70
Response: {
71
  "value": {
72
    "sessionId": "string",
73
    "capabilities": { "browserName": "firefox", ... }
74
  }
75
}
76

77
// Add node to distributor
78
POST /se/grid/distributor/node
79
Content-Type: application/json
80
{
81
  "id": "uuid",
82
  "uri": "http://node-host:port",
83
  "capacity": {
84
    "available": [
85
      { "capabilities": { "browserName": "chrome", "maxInstances": 5 }, "count": 5 }
86
    ]
87
  }
88
}
89

90
// Remove node from distributor
91
DELETE /se/grid/distributor/node/{nodeId}
92
Response: HTTP 200 OK
93

94
// Get distributor status
95
GET /status
96
Response: {
97
  "value": {
98
    "ready": true,
99
    "message": "Distributor is ready",
100
    "nodes": [...]
101
  }
102
}
103
```
104

105
### Node Endpoints
106

107
Node endpoints handle session creation, WebDriver command execution, and node status reporting.
108

109
```java { .api }
110
// Create session on this node
111
POST /se/grid/node/session
112
Content-Type: application/json
113
{
114
  "capabilities": { "browserName": "chrome" }
115
}
116
Response: {
117
  "sessionId": "string",
118
  "capabilities": { "browserName": "chrome", ... }
119
}
120

121
// Get session details
122
GET /se/grid/node/session/{sessionId}
123
Response: {
124
  "sessionId": "string",
125
  "capabilities": { ... },
126
  "uri": "http://node-host:port"
127
}
128

129
// Stop session on this node
130
DELETE /se/grid/node/session/{sessionId}
131
Response: HTTP 200 OK
132

133
// Check if node owns session
134
GET /se/grid/node/owner/{sessionId}
135
Response: {
136
  "value": true  // or false
137
}
138

139
// Get node status
140
GET /status
141
Response: {
142
  "value": {
143
    "ready": true,
144
    "message": "Node is ready",
145
    "capacity": {
146
      "available": [...],
147
      "used": [...]
148
    }
149
  }
150
}
151

152
// Forward WebDriver commands (any WebDriver endpoint)
153
* /session/{sessionId}/*
154
// All standard WebDriver commands are supported
155
```
156

157
### Data Formats
158

159
#### Session Data Format
160

161
Standard session representation used across Grid components.
162

163
```java { .api }
164
// Session JSON structure
165
{
166
  "sessionId": "string",           // Unique session identifier
167
  "capabilities": {                // Browser capabilities
168
    "browserName": "chrome",
169
    "browserVersion": "91.0",
170
    "platformName": "linux"
171
  },
172
  "uri": "http://node-host:port"   // Node URI hosting the session
173
}
174
```
175

176
#### Node Status Format
177

178
Node status information including capacity and current usage.
179

180
```java { .api }
181
// NodeStatus JSON structure
182
{
183
  "id": "uuid",                    // Unique node identifier
184
  "uri": "http://node-host:port",  // Node URI
185
  "capacity": {
186
    "available": [
187
      {
188
        "capabilities": {          // Available browser capabilities
189
          "browserName": "chrome",
190
          "maxInstances": 5
191
        },
192
        "count": 3                 // Available instances
193
      }
194
    ],
195
    "used": [
196
      {
197
        "capabilities": {          // Used browser capabilities
198
          "browserName": "chrome"
199
        },
200
        "count": 2                 // Used instances
201
      }
202
    ]
203
  }
204
}
205
```
206

207
#### WebDriver Request/Response Format
208

209
All WebDriver endpoints follow W3C WebDriver specification format.
210

211
```java { .api }
212
// Standard WebDriver response format
213
{
214
  "value": {                       // Response data
215
    // Command-specific response data
216
  },
217
  "status": 0,                     // Optional status code (legacy)
218
  "sessionId": "string"            // Session ID (when applicable)
219
}
220

221
// WebDriver error response format
222
{
223
  "value": {
224
    "error": "no such element",    // Error code
225
    "message": "Element not found", // Human-readable message
226
    "stacktrace": "..."            // Stack trace (optional)
227
  }
228
}
229
```
230

231
### Error Handling
232

233
The API returns standard WebDriver error responses following W3C WebDriver specification:
234

235
```java { .api }
236
// Common error types
237
"invalid session id"             // Session not found or expired
238
"no such element"               // Element not found
239
"element not interactable"      // Element cannot be interacted with
240
"session not created"           // Failed to create session
241
"timeout"                       // Operation timed out
242
"unknown error"                 // General server error
243
```
244

245
### Content Types
246

247
All endpoints expect and return JSON data with appropriate Content-Type headers:
248

249
```java { .api }
250
// Request headers
251
Content-Type: application/json; charset=utf-8
252

253
// Response headers  
254
Content-Type: application/json; charset=utf-8
255
```
256

257
### HTTP Status Codes
258

259
Standard HTTP status codes are used throughout the API:
260

261
```java { .api }
262
200 OK                          // Successful operation
263
201 Created                     // Resource created successfully
264
400 Bad Request                 // Invalid request format
265
404 Not Found                   // Resource not found
266
500 Internal Server Error       // Server error
267
```