Improve documentation of Stork API (SwaggerUI)
There is documentation of the Stork API in the Stork UI under "Help -> Stork API Docs (SwaggerUI)". This documentation is really good, especially the "try it out" functionality. Unfortunately, the "try it out" seems to always work no matter if you have set things properly by clicking the Lock icon, or made a mistake there. Therefore, it is somewhat difficult to figure out the actual process to come up with the session key to use during the API calls. I propose to resolve this by adding a simple example with accompanying short instruction so that it is more obvious how to use the API. It is really easy once you understand this step!
Example
$ curl -v -X 'POST' 'http://192.168.20.10:8080/api/sessions' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{"authenticationMethodId": "internal", "identifier": "admin", "secret": "admin"}' | jq
Note: Unnecessary use of -X or --request, POST is already inferred.
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 192.168.20.10:8080...
* Connected to 192.168.20.10 (192.168.20.10) port 8080 (#0)
> POST /api/sessions HTTP/1.1
> Host: 192.168.20.10:8080
> User-Agent: curl/7.88.1
> accept: application/json
> Content-Type: application/json
> Content-Length: 80
>
} [80 bytes data]
< HTTP/1.1 200 OK
< Cache-Control: no-cache="Set-Cookie"
< Content-Type: application/json
< Set-Cookie: session=L0cdSK9h6l_Cm4UY7D-Fsw_HWPmkYN0HwfnB5oNlI5U; Path=/; Expires=Thu, 30 Nov 2023 12:17:18 GMT; Max-Age=86400; HttpOnly; SameSite=Lax
< Vary: Cookie
< Date: Wed, 29 Nov 2023 12:17:17 GMT
< Content-Length: 108
<
{ [108 bytes data]
100 188 100 108 100 80 12253 9076 --:--:-- --:--:-- --:--:-- 23500
* Connection #0 to host 192.168.20.10 left intact
{
"authenticationMethodId": "internal",
"groups": [
1
],
"id": 1,
"lastname": "admin",
"login": "admin",
"name": "admin"
}
$ curl -v -X 'GET' 'http://192.168.20.10:8080/api/shared-networks' -H 'accept: application/json' -H 'Cookie: session=L0cdSK9h6l_Cm4UY7D-Fsw_HWPmkYN0HwfnB5oNlI5U' | jq
Note: Unnecessary use of -X or --request, GET is already inferred.
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 192.168.20.10:8080...
* Connected to 192.168.20.10 (192.168.20.10) port 8080 (#0)
> GET /api/shared-networks HTTP/1.1
> Host: 192.168.20.10:8080
> User-Agent: curl/7.88.1
> accept: application/json
> Cookie: session=L0cdSK9h6l_Cm4UY7D-Fsw_HWPmkYN0HwfnB5oNlI5U
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Vary: Cookie
< Date: Wed, 29 Nov 2023 12:17:38 GMT
< Content-Length: 15
<
{ [15 bytes data]
100 15 100 15 0 0 6407 0 --:--:-- --:--:-- --:--:-- 7500
* Connection #0 to host 192.168.20.10 left intact
{
"items": null
}
Instructions based on the example
- First a login must be performed:
$ curl -v -X 'POST' 'http://192.168.20.10:8080/api/sessions' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{"authenticationMethodId": "internal", "identifier": "admin", "secret": "admin"}'
The"identifier": "admin"
and"secret": "admin"
should match a username and password that can log into the Stork UI. - The return, if authentication is successful, will contain (in the header) something like this:
< Set-Cookie: session=L0cdSK9h6l_Cm4UY7D-Fsw_HWPmkYN0HwfnB5oNlI5U; Path=/; Expires=Thu, 30 Nov 2023 12:17:18 GMT; Max-Age=86400; HttpOnly; SameSite=Lax
- Subsequent calls, for the next 24 hours, must include:
session=L0cdSK9h6l_Cm4UY7D-Fsw_HWPmkYN0HwfnB5oNlI5U
as shown here:$ curl -v -X 'GET' 'http://192.168.20.10:8080/api/shared-networks' -H 'accept: application/json' -H 'Cookie: session=L0cdSK9h6l_Cm4UY7D-Fsw_HWPmkYN0HwfnB5oNlI5U'
Of course, the above is only a suggestion. There may be better examples and subsequent instructions, and/or a more dynamic way that could include data from the local StorkUI the user is actually using, which would be even easier to understand.