[notnarb]

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

[imglorp]

Instead of org and curl, some might like to give restclient a call. You put a # comment, then a rest call and maybe some data. It's still organized like a notebook, though, so you can point to any call and punch Ctrl-return and the result pops up in another buffer. Simple and slick without all the Org markup.

https://github.com/pashky/restclient.el

[emacsgifs]

Are we assuming everyone knows that Org-mode is an Emacs package?

[lucideer]

As someone who has never used Org-mode, and only very briefly dabbled in Emacs during college, I actually think that's a pretty safe assumption around these parts. No?

[traviscj]

Even if you are uncomfortable assuming that, search results for "org-mode"/"orgmode" are unambiguous and helpful for anyone out-of-the-loop and curious, so it doesn't seem exclusionary or like a secret in-joke reserved for a secret society of HN elite.

[emacsgifs]

I'm far more uncomfortable assuming everyone has the interest to follow up on every comment.

Alternatively I prefer to assume that it'll give our commentary more value if we provide some helpful context.

If our goal is to share technologies that we think are useful, we have options to make that goal more successful.

[traviscj]

This is really cool. I end up doing a lot of this kind of stuff at work, so I plan on using the bejesus out of this.