ipernity / ShellScript API Kit (v0.9)

This toolkit provides some basic functions to perform some API calls, including user authentication. Results can be returned in JSON, PHP or XML.

Installation

Download Iper_API, untar and place the Iper_API.sh file where needed.

You need the following installed: tr, cut, awk, sort, md5sum, curl, hexdump

How to use

(see also test_API.sh)

1. First, load the API from your script

. /path/to/Iper_API.sh

2. define your API key and secret, and select the response format

By example:

APIKEY=123456789abcdef0123456789abcdef0
APISECRET=123456789abcdef0
APIFORMAT=json

Keep your secret safe!

3. Now, you need the user to grant you the necessary permissions

1. Get a temporary FROB from ipernity

JSON_STRING=`call_api_method $APIKEY $APISECRET $APIFORMAT auth.getFrob`
FROB=`echo "$JSON_STRING" | tr "\"" " " | awk ' { print $6 } '`

2. Ask the user to go to ipernity and grant permissions to the FROB owner (you)

echo "Goto "`get_user_auth $APIKEY $APISECRET $FROB perm_doc=write perm_blog=write`
echo "and grant the permissions, then press <ENTER>"; read LINE

3. Exchange the temporary FROB for a definitive TOKEN

JSON_STRING=`call_api_method $APIKEY $APISECRET $APIFORMAT auth.getToken frob=$FROB`
TOKEN=`echo "$JSON_STRING" | tr "\"" " " | awk ' { print $6 } '`

4. Then, with this TOKEN, you are ready to make authenticated queries

You will only need to redo the 3 previous steps if you lose the TOKEN, if you need different permissions, or if the user revoked your application.

Documentation

call_api_method <APIKEY> <APISECRET> <APIFORMAT> <METHOD> [<PARAMS>...]

<APIKEY> : your API key.
<APISECRET> : your API secret.
<APIFORMAT> : the API response format (json, php, xml).
<METHOD> : the API method to call.
<PARAMS> : the parameters to send. (eg. p1=a p2=b...)

By example:

call_api_method $APIKEY $APISECRET $APIFORMAT account.getQuota auth_token=$TOKEN

For options that takes strings (with spaces) as parameters, be sure to quote the strings. eg. title="Hello World"

get_user_auth <APIKEY> <APISECRET> <FROB> <PERMISSION> [<PERMISSION>...]

<APIKEY> : your API key.
<APISECRET> : your API secret.
<FROB> : the temporary FROB you got from ipernity.
<PERMISSION>s : the permissions you will need from the user. (eg. perm_doc=write...)

By example:

get_user_auth $APIKEY $APISECRET $FROB perm_doc=write perm_blog=write

More examples

call_api_method $APIKEY $APISECRET $APIFORMAT auth.checkToken auth_token=$TOKEN
call_api_method $APIKEY $APISECRET $APIFORMAT doc.tags.add auth_token=$TOKEN doc_id=123456 keywords=black,white
call_api_method $APIKEY $APISECRET $APIFORMAT doc.comments.add auth_token=$TOKEN doc_id=123456 content="This is a comment"
call_api_method $APIKEY $APISECRET $APIFORMAT doc.comments.add auth_token=$TOKEN doc_id=123456 content="This is another comment"
call_api_method $APIKEY $APISECRET $APIFORMAT doc.comments.add auth_token=$TOKEN doc_id=123456 content="This is a third comment"
call_api_method $APIKEY $APISECRET $APIFORMAT doc.comments.delete auth_token=$TOKEN doc_id=123456 comment_id=1234
call_api_method $APIKEY $APISECRET $APIFORMAT doc.set auth_token=$TOKEN doc_id=123456 title="Hello" description="Hello World"
call_api_method $APIKEY $APISECRET $APIFORMAT doc.get auth_token=$TOKEN doc_id=123456 extra=tags,notes,geo
call_api_method $APIKEY $APISECRET $APIFORMAT doc.getPerms auth_token=$TOKEN doc_id=123456
call_api_method $APIKEY $APISECRET $APIFORMAT doc.comments.getList auth_token=$TOKEN doc_id=123456
call_api_method $APIKEY $APISECRET $APIFORMAT upload.file auth_token=$TOKEN file=acme.png

One last thing...

Have fun and let us know if you need any help.