Skip to content

Commit 560e9e3

Browse files
Simran-BSimran-B
authored
HTTP API: Unify wording of result objects (#788)
* Unify error, code, and errorMessage * Unify errorNum and a few more code * Fix inconsistencies discovered by Cursor, apply some changes from 3.12 to 3.11
1 parent 4b1b440 commit 560e9e3

40 files changed

+667
-486
lines changed

‎site/content/3.11/develop/http-api/administration.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,7 @@ paths:
2222
# Technically accepts all of the following methods: HEAD, GET, POST, PATCH, PUT, DELETE
2323
operationId: getVersion
2424
description: |
25-
Returns the server name and version number. The response is a JSON object
26-
with the following attributes:
25+
Returns the server name and version number.
2726
parameters:
2827
- name: database-name
2928
in: path
@@ -246,7 +245,6 @@ paths:
246245
operationId: getEngine
247246
description: |
248247
Returns the storage engine the server is configured to use.
249-
The response is a JSON object with the following attributes:
250248
parameters:
251249
- name: database-name
252250
in: path
@@ -329,12 +327,14 @@ paths:
329327
properties:
330328
error:
331329
description: |
332-
boolean flag to indicate whether an error occurred (`false` in this case)
330+
A flag indicating that no error occurred.
333331
type: boolean
332+
example: false
334333
code:
335334
description: |
336-
the HTTP status code
335+
The HTTP response status code.
337336
type: integer
337+
example: 200
338338
time:
339339
description: |
340340
The current system time as a Unix timestamp with microsecond precision of the server
@@ -959,7 +959,7 @@ paths:
959959
in: query
960960
required: false
961961
description: |
962-
Set to `true` to change the license even if it expires sooner than the current one.
962+
Whether to change the license even if it expires sooner than the current one.
963963
schema:
964964
type: boolean
965965
default: false
@@ -968,7 +968,7 @@ paths:
968968
application/json:
969969
schema:
970970
description: |
971-
The request body has to contain the Base64-encoded string wrapped in double quotes.
971+
The request body has to contain the Base64-encoded license string wrapped in double quotes.
972972
type: string
973973
example: eyJncmFudCI6...(Base64-encoded license string)...
974974
responses:
@@ -995,7 +995,7 @@ paths:
995995
example: false
996996
code:
997997
description: |
998-
The HTTP status code.
998+
The HTTP response status code.
999999
type: integer
10001000
example: 201
10011001
'400':
@@ -1019,12 +1019,12 @@ paths:
10191019
example: true
10201020
code:
10211021
description: |
1022-
The HTTP status code.
1022+
The HTTP response status code.
10231023
type: integer
10241024
example: 400
10251025
errorNum:
10261026
description: |
1027-
The ArangoDB error number.
1027+
The ArangoDB error number for the error that occurred.
10281028
type: integer
10291029
errorMessage:
10301030
description: |
@@ -1050,12 +1050,12 @@ paths:
10501050
example: true
10511051
code:
10521052
description: |
1053-
The HTTP status code.
1053+
The HTTP response status code.
10541054
type: integer
10551055
example: 501
10561056
errorNum:
10571057
description: |
1058-
The ArangoDB error number.
1058+
The ArangoDB error number for the error that occurred.
10591059
type: integer
10601060
errorMessage:
10611061
description: |

‎site/content/3.11/develop/http-api/authentication.md‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,8 @@ If you use a tool like cURL, you can manually specify this header as follows:
9090
curl -H 'Authorization: Basic dXNlcjpwYXNz' ...
9191
```
9292

93-
However, cURL can also take care of the authentication for you:
93+
However, cURL can also take care of the authentication and specifically the
94+
encoding of the credentials for you:
9495

9596
```
9697
curl -u user:pass ...
@@ -114,19 +115,19 @@ For more information on JWT please consult RFC7519 and [jwt.io](https://jwt.io).
114115

115116
### JWT user tokens
116117

117-
To authenticate with a specific user you need to supply a JWT token containing
118-
the `preferred_username` field with the username.
118+
To authenticate with a specific user account, you need to supply a JWT token
119+
containing the `preferred_username` field with the username.
119120
You can either let ArangoDB generate this token for you via an API call
120121
or you can generate it yourself (only if you know the JWT secret).
121122

122123
ArangoDB offers a RESTful API to generate user tokens for you if you know the
123-
username and password. To do so send a POST request to:
124+
username and password. To do so, send a POST request to this endpoint:
124125

125126
```
126127
/_open/auth
127128
```
128129

129-
… containing `username` and `password` JSON-encoded like so:
130+
The request body needs to contain the `username` and `password` JSON-encoded like so:
130131

131132
```json
132133
{
@@ -203,7 +204,8 @@ paths:
203204
type: string
204205
responses:
205206
'200':
206-
description: ''
207+
description: |
208+
Successfully created a session token.
207209
content:
208210
application/json:
209211
schema:
@@ -304,7 +306,8 @@ paths:
304306
type: string
305307
responses:
306308
'200':
307-
description: ''
309+
description: |
310+
Successfully retrieved the JWT secret information.
308311
content:
309312
application/json:
310313
schema:
@@ -318,12 +321,14 @@ paths:
318321
properties:
319322
error:
320323
description: |
321-
boolean flag to indicate whether an error occurred (`false` in this case)
324+
A flag indicating that no error occurred.
322325
type: boolean
326+
example: false
323327
code:
324328
description: |
325-
the HTTP status code - 200 in this case
329+
The HTTP response status code.
326330
type: integer
331+
example: 200
327332
result:
328333
description: |
329334
The result object.
@@ -370,7 +375,8 @@ paths:
370375
will be _HTTP 403 Forbidden_.
371376
responses:
372377
'200':
373-
description: ''
378+
description: |
379+
Successfully reloaded the JWT secrets.
374380
content:
375381
application/json:
376382
schema:
@@ -384,12 +390,14 @@ paths:
384390
properties:
385391
error:
386392
description: |
387-
boolean flag to indicate whether an error occurred (`false` in this case)
393+
A flag indicating that no error occurred.
388394
type: boolean
395+
example: false
389396
code:
390397
description: |
391-
the HTTP status code - 200 in this case
398+
The HTTP response status code.
392399
type: integer
400+
example: 200
393401
result:
394402
description: |
395403
The result object.

‎site/content/3.11/develop/http-api/cluster.md‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -121,12 +121,14 @@ paths:
121121
properties:
122122
error:
123123
description: |
124-
boolean flag to indicate whether an error occurred (`true` in this case)
124+
A flag indicating that an error occurred.
125125
type: boolean
126+
example: true
126127
code:
127128
description: |
128-
the HTTP status code - 200
129+
The HTTP response status code.
129130
type: integer
131+
example: 200
130132
endpoints:
131133
description: |
132134
A list of active cluster endpoints.
@@ -196,15 +198,17 @@ paths:
196198
properties:
197199
error:
198200
description: |
199-
always `false`
201+
A flag indicating that no error occurred.
200202
type: boolean
203+
example: false
201204
code:
202205
description: |
203-
the HTTP status code, always 200
206+
The HTTP response status code.
204207
type: integer
208+
example: 200
205209
errorNum:
206210
description: |
207-
the server error number
211+
The ArangoDB error number for the error that occurred.
208212
type: integer
209213
role:
210214
description: |
@@ -302,12 +306,14 @@ paths:
302306
properties:
303307
error:
304308
description: |
305-
Whether an error occurred. `false` in this case.
309+
A flag indicating that no error occurred.
306310
type: boolean
311+
example: false
307312
code:
308313
description: |
309-
The status code. `200` in this case.
314+
The HTTP response status code.
310315
type: integer
316+
example: 200
311317
result:
312318
description: |
313319
The result object with the status. This attribute is omitted if the DB-Server
@@ -395,8 +401,9 @@ paths:
395401
properties:
396402
error:
397403
description: |
398-
Whether an error occurred. `false` in this case.
404+
A flag indicating that no error occurred.
399405
type: boolean
406+
example: false
400407
code:
401408
description: |
402409
The status code. `200` in this case.
@@ -659,12 +666,14 @@ paths:
659666
properties:
660667
code:
661668
description: |
662-
The status code.
663-
type: number
669+
The HTTP response status code.
670+
type: integer
671+
example: 200
664672
error:
665673
description: |
666-
Whether an error occurred. `false` in this case.
674+
A flag indicating that no error occurred.
667675
type: boolean
676+
example: false
668677
result:
669678
description: |
670679
The result object.
@@ -866,12 +875,14 @@ paths:
866875
properties:
867876
code:
868877
description: |
869-
The status code.
870-
type: number
878+
The HTTP response status code.
879+
type: integer
880+
example: 200
871881
error:
872882
description: |
873-
Whether an error occurred. `false` in this case.
883+
A flag indicating that no error occurred.
874884
type: boolean
885+
example: false
875886
result:
876887
description: |
877888
The result object.
@@ -1283,12 +1294,14 @@ paths:
12831294
properties:
12841295
code:
12851296
description: |
1286-
The status code.
1287-
type: number
1297+
The HTTP response status code.
1298+
type: integer
1299+
example: 200
12881300
error:
12891301
description: |
1290-
Whether an error occurred. `false` in this case.
1302+
A flag indicating that no error occurred.
12911303
type: boolean
1304+
example: false
12921305
result:
12931306
description: |
12941307
The result object.

0 commit comments

Comments
 (0)