Document example a few example API requests

[britton-jb]

Document example API authentication, and authenticated request after authentication for those not familiar with the way Guardian works.

[sgeos]

Is there a way to POST login information and get a token back via the API? It seems like an older version of Sentinel had that functionality, although I may have hand rolled it. In any case, it seems like a reasonable thing to provide out of the box.

[britton-jb]

Looks like in v2 with the Ueberauth addition I must have removed that. I'll work on adding that back in. In the meantime you should be able to achieve that by posting to /auth/session.

Sorry about that oversight.

[sgeos]

I look forward to a resolution to this regression.

Just in case anyone else runs into this problem, something like the following can be used to get a guardian token from the command line by posting to /auth/session.

EMAIL=me@example.com
PASSWORD=my_password
HOST=http://localhost:8080
COOKIE_FILE=$(mktemp /tmp/api_auth_session_html.cookie.XXXXXX)
curl -s -c "${COOKIE_FILE}" -X POST -F "session[email]=${EMAIL}" -F "session[password]=${PASSWORD}" "${HOST}/auth/session" 2>/dev/null > /dev/null
curl -s -b "${COOKIE_FILE}" -X GET "${HOST}" | grep guardian_token | sed -e 's/^.*content="//g' | sed -e 's/".*$//g'
rm -f "${COOKIE_FILE}"

[britton-jb]

Forgot about this one during my review process. I'll add it to the features/lockable_and_plug branch changes, which include a number of other changes.