HTTP API reference with curl examples

[spl]

1. Combine HTTP API Reference with CURL Reference into HTTP API Reference
2. Remove CURL Reference page
3. Use curl (and httpie/xh?) as examples for those endpoints
4. Bring over changes from the v10.0 branch

[spl]

I will move md/reference/reference-document-interface.md into this.

[spl]

We need to develop more documentation on the query parameter of the /api/document endpoint.

[montaropdf]

Hello,

I tried to create a new user following the documentation, but terminusdb complains that the user cannot be updated because it doesn't exists, instead.

As I suspect an issue with the documentation instead of the DB, I report this problem here.

Creation of a user with a password

curl -u "$TDB_USER:$TDB_PASSWD" "$TDB_BASE/api/user" -v -X POST -H "Content-Type: application/json" \
> -d @- <<EOF
heredoc> { "user_identifier" : "sandboxer",
}
"agent_name" : "Smith",
"comment" : "User for playing with terminusdb features" ,
"password" : "Password"
}
heredoc> EOF
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying ::1:6363...
* connect to ::1 port 6363 failed: Connexion refusée
*   Trying 127.0.0.1:6363...
* Connected to localhost (127.0.0.1) port 6363 (#0)
* Server auth using Basic with user 'admin'
> POST /api/user HTTP/1.1
> Host: localhost:6363
> Authorization: Basic YWRtaW46cm9vdA==
> User-Agent: curl/7.76.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 144
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 500 Internal Server Error
< Date: Thu, 06 Jan 2022 12:36:54 GMT
< Connection: Keep-Alive
< Content-Type: application/json
< Content-Length: 881
<
{
"api:message":"Error: user_cannot_update_as_they_dont_exist(\"Smith\",_18770{agent_name:\"Smith\",comment:\"User for playing with terminusdb features\",password:\"Password\",user_identifier:\"sandboxer\"})\n  [33] throw(error(user_cannot_update_as_they_dont_exist(\"Smith\",...),_18836))\n  [31] '<meta-call>'(routes:(...,...)) <foreign>\n  [30] catch(routes:(...,...),error(user_cannot_update_as_they_dont_exist(\"Smith\",...),context(_18950,_18952)),routes:do_or_die(...,...)) at /usr/lib/swipl/boot/init.pl:561\n  [29] catch_with_backtrace(routes:(...,...),error(user_cannot_update_as_they_dont_exist(\"Smith\",...),context(_19026,_19028)),routes:do_or_die(...,...)) at /usr/lib/swipl/boot/init.pl:629\n\nNote: some frames are missing due to last-call optimization.\nRe-run your program in debug mode (:- debug.) to get more detail.\n\n",
"api:status":"api:server_error"
* Connection #0 to host localhost left intact
}%

Creation of a user omitting the password field

curl -u "$TDB_USER:$TDB_PASSWD" "$TDB_BASE/api/user" -v -X POST -H "Content-Type: application/json" \
-d @- <<EOF
{ "user_identifier" : "sandboxer",
"agent_name" : "Smith",
"comment" : "User for playing with terminusdb features"
}
EOF
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying ::1:6363...
* connect to ::1 port 6363 failed: Connexion refusée
*   Trying 127.0.0.1:6363...
* Connected to localhost (127.0.0.1) port 6363 (#0)
* Server auth using Basic with user 'admin'
> POST /api/user HTTP/1.1
> Host: localhost:6363
> Authorization: Basic YWRtaW46cm9vdA==
> User-Agent: curl/7.76.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 117
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 500 Internal Server Error
< Date: Thu, 06 Jan 2022 12:38:11 GMT
< Connection: Keep-Alive
< Content-Type: application/json
< Content-Length: 859
<
{
"api:message":"Error: user_cannot_update_as_they_dont_exist(\"Smith\",_18564{agent_name:\"Smith\",comment:\"User for playing with terminusdb features\",user_identifier:\"sandboxer\"})\n  [33] throw(error(user_cannot_update_as_they_dont_exist(\"Smith\",...),_18626))\n  [31] '<meta-call>'(routes:(...,...)) <foreign>\n  [30] catch(routes:(...,...),error(user_cannot_update_as_they_dont_exist(\"Smith\",...),context(_18740,_18742)),routes:do_or_die(...,...)) at /usr/lib/swipl/boot/init.pl:561\n  [29] catch_with_backtrace(routes:(...,...),error(user_cannot_update_as_they_dont_exist(\"Smith\",...),context(_18816,_18818)),routes:do_or_die(...,...)) at /usr/lib/swipl/boot/init.pl:629\n\nNote: some frames are missing due to last-call optimization.\nRe-run your program in debug mode (:- debug.) to get more detail.\n\n",
"api:status":"api:server_error"
* Connection #0 to host localhost left intact
}%