For people already used to org-mode + curl (or any CLI tool), I highly recommend using those together when exploring an API (granted, this involves throwing simplicity out the window)
:PROPERTIES:
:header-args: shell :var PASSWORD=not :var USERNAME=narb :var AUTH_URL="nova.example.com:5000/v2.0/tokens"
:END:
...
#+NAME: get-openstack-token
#+BEGIN_SRC shell :cache yes :results verbatim
export DATA='{
"auth" : {
"tenantName": "'"$TENANT_NAME"'",
"passwordCredentials": {
"username": "'"$USERNAME"'",
"password": "'"$PASSWORD"'"
}
}
}'
curl -s $AUTH_URL \
-H "Content-Type: application/json" \
--data "$DATA" | jq -r ".access.token.id"
#+END_SRC
#+RESULTS[be67...]: get-openstack-token
: deadbeefdeadbeefdeadbeef
...
#+BEGIN_SRC shell :var AUTH_TOKEN=get-openstack-token
curl -H "X-AUTH-TOKEN: $AUTH_TOKEN"
...
Not to discount tools such as postman / insomnia or other built-in editor tools like restclient-mode, they are all fantastic tools
Some quick reasons why I found this works best for me:
* Org-mode is already great as a dedicated note-taking tool
* This is immediately compatible with existing CLI examples or output from tools that offer 'export as cURL' -- this is especially useful if I want to reverse engineer an api request by browser is making
* Easy to export to an html/wiki document for immediate consumption by others with working CLI examples
* Composable with other CLI tools like jq and xmllint
* Plain-text files are easy to version control