diff --git a/docs/Readme.markdown b/docs/Readme.markdown index 189b567..41b1019 100644 --- a/docs/Readme.markdown +++ b/docs/Readme.markdown @@ -3,3 +3,6 @@ OpenPhoto / Documentation You can find the documentation at http://theopenphotoproject.org/documentation. It's a mirror of what is here but easier to follow. +If you'd like to contribute to the documentation, please do! We welcome any and all contributions. Fork this repository (documentation) and add your contribution, then send a pull request. The docs/contribute/documentation.markdown in this repository explains everything you need to more. + +Questions? We're here to help. Email our mailing list at openphoto@googlegroups.com or ask in #openphoto on Freenode. diff --git a/docs/configs/readme.markdown b/docs/configs/readme.markdown new file mode 100644 index 0000000..b956dc2 --- /dev/null +++ b/docs/configs/readme.markdown @@ -0,0 +1,3 @@ +Your Trovebox installation comes with a number of configuration files and settings. This section explains the settings and what you can set them to. + +Questions? We can help. Send us an email at openphoto@googlegroups.com or ask in #openphoto on Freenode. diff --git a/docs/libraries/php.markdown b/docs/libraries/php.markdown new file mode 100644 index 0000000..3a49fcd --- /dev/null +++ b/docs/libraries/php.markdown @@ -0,0 +1,97 @@ +Open Photo API / PHP Library +======================= +#### OpenPhoto, a photo service for the masses + +---------------------------------------- + + +### How to use the library + +To use the library you need to first include `OpenPhotoOAuth.php`, then instantiate an instance of the class and start making calls. + + include 'OpenPhotoOAuth.php'; + $client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $token, $tokenSecret); + $resp = $client->get('/photos/list.json'); + $resp = $client->post('/photo/62/update.json', array('tags' => 'tag1,tag2')); + +---------------------------------------- + + +### Using from the command line + +Make sure that the `openphoto` file is executable. + + chown o+x openphoto + +You'll then want to export your secrets to the environment. +We suggest putting them in a file and sourcing it prior to running `openphoto` commands. +Click here for instructions on getting credentials. + + # env.sh + export consumerKey=your_consumer_key + export consumerSecret=your_consumer_secret + export token=your_access_token + export tokenSecret=your_access_token_secret + +You'll need to source that file once for each terminal session. + + source env.sh + +These are the options you can pass to the shell program. + + -h hostname # default=localhost + -e endpoint # default=/photos/list.json + -X method # default=GET + -F params # i.e. -F 'title=my title' -F 'tags=mytag1,mytag1' + -p # pretty print the json + -v # verbose output + --encode # base 64 encode the photo + +Now you can run commands to the OpenPhoto API from your shell! + + ./openphoto -h current.openphoto.me -p -e /photo/62/view.json -F 'returnSizes=20x20' + { + "message" : "Photo 62", + "code" : 200, + "result" : { + "tags" : [ + + ], + "id" : "62", + "appId" : "current.openphoto.me", + "pathBase" : "\/base\/201108\/1312956581-opmeqViHrD.jpg", + "dateUploadedMonth" : "08", + "dateTakenMonth" : "08", + "exifCameraMake" : "", + "dateTaken" : "1312956581", + "title" : "Tomorrowland Main Stage 2011", + "height" : "968", + "description" : "", + "creativeCommons" : "BY-NC", + "dateTakenYear" : "2011", + "dateUploadedDay" : "09", + "longitude" : "4", + "host" : "opmecurrent.s3.amazonaws.com", + "hash" : "0455675a8c42148238b81ed1d8db655c45ae055a", + "status" : "1", + "width" : "1296", + "dateTakenDay" : "09", + "permission" : "1", + "pathOriginal" : "\/original\/201108\/1312956581-opmeqViHrD.jpg", + "size" : "325", + "dateUploadedYear" : "2011", + "views" : "0", + "latitude" : "50.8333", + "dateUploaded" : "1312956583", + "exifCameraModel" : "", + "Name" : "62", + "path20x20" : "http:\/\/current.openphoto.me\/photo\/62\/create\/ceb90\/20x20.jpg" + } + } + + +#### Getting your credentials + +You can get your credentals by clicking on the arrow next to your email address once you're logged into your site and then clicking on settings. +If you don't have any credentials then you can create one for yourself by going to `/v1/oauth/flow`. +Once completed go back to the settings page and you should see the credential you just created diff --git a/docs/libraries/python.markdown b/docs/libraries/python.markdown new file mode 100644 index 0000000..ad8c113 --- /dev/null +++ b/docs/libraries/python.markdown @@ -0,0 +1,131 @@ +Open Photo API / Python Library +======================= +#### OpenPhoto, a photo service for the masses +[![Build Status](https://api.travis-ci.org/photo/openphoto-python.png)](https://travis-ci.org/photo/openphoto-python) + +---------------------------------------- + +### Installation + python setup.py install + +---------------------------------------- + +### Credentials + +For full access to your photos, you need to create the following config file in ``~/.config/openphoto/default`` + + # ~/.config/openphoto/default + host = your.host.com + consumerKey = your_consumer_key + consumerSecret = your_consumer_secret + token = your_access_token + tokenSecret = your_access_token_secret + +The ``config_file`` switch lets you specify a different config file. + +To get your credentials: + * Log into your Trovebox site + * Click the arrow on the top-right and select 'Settings' + * Click the 'Create a new app' button + * Click the 'View' link beside the newly created app + +---------------------------------------- + +### How to use the library + +You can use the library in one of two ways: + + * Direct GET/POST calls to the server + * Access via Python classes/methods + + +#### Direct GET/POST: + + from openphoto import OpenPhoto + client = OpenPhoto() + resp = client.get("/photos/list.json") + resp = client.post("/photo/62/update.json", tags=["tag1", "tag2"]) + + +#### Python classes/methods + + from openphoto import OpenPhoto + client = OpenPhoto() + photos = client.photos.list() + photos[0].update(tags=["tag1", "tag2"]) + print photos[0].tags + +The OpenPhoto Python class hierarchy mirrors the [OpenPhoto API](http://theopenphotoproject.org/documentation) endpoint layout. For example, the calls in the example above use the following API endpoints: + +* ``client.photos.list() -> /photos/list.json`` +* ``photos[0].update() -> /photo//update.json`` + + +### API Versioning + +It may be useful to lock your application to a particular version of the OpenPhoto API. +This ensures that future API updates won't cause unexpected breakages. + +To do this, add the optional ```api_version``` parameter when creating the client object: + + from openphoto import OpenPhoto + client = OpenPhoto(api_version=2) + +---------------------------------------- + + +### Using from the command line + +You can run commands to the OpenPhoto API from your shell! + +These are the options you can pass to the shell program: + + --help # Display help text + -c config_file # Either the name of a config file in ~/.config/openphoto/ or a full path to a config file + -h hostname # Overrides config_file for unauthenticated API calls + -e endpoint # [default=/photos/list.json] + -X method # [default=GET] + -F params # e.g. -F 'title=my title' -F 'tags=mytag1,mytag2' + -p # Pretty print the json + -v # Verbose output + + +#### Command line examples + + # Upload a public photo to the host specified in ~/.config/openphoto/default + openphoto -p -X POST -e /photo/upload.json -F 'photo=@/path/to/photo/jpg' -F 'permission=1' + { + "code":201, + "message":"Photo 1eo uploaded successfully", + "result":{ + "actor":"user@example.com", + "albums":[], + ... + ... + } + } + + # Get a thumbnail URL from current.openphoto.me (unauthenticated access) + openphoto -h current.openphoto.me -p -e /photo/62/view.json -F 'returnSizes=20x20' + { + "code":200, + "message":"Photo 62", + "result":{ + "actor":"", + "albums":[ + "1" + ], + ... + ... + "path20x20":"http://current.openphoto.me/photo/62/create/36c0a/20x20.jpg", + "pathBase":"http://awesomeness.openphoto.me/base/201203/7ae997-Boracay-Philippines-007.jpg", + "permission":"1", + "photo20x20":[ + "http://current.openphoto.me/photo/62/create/36c0a/20x20.jpg", + 13, + 20 + ], + ... + ... + } + } diff --git a/docs/libraries/readme.markdown b/docs/libraries/readme.markdown new file mode 100644 index 0000000..2b7f4f8 --- /dev/null +++ b/docs/libraries/readme.markdown @@ -0,0 +1,12 @@ +If you're looking for our language libraries, you're in the right place. The documentation for our various language libraries lives here. + +Currently we have libraries for: + +* PHP +* Python +* Javascript +* Java +* Objective-C +* Ruby + +Is your favorite language not listed? Contact us or better yet, write your own. diff --git a/docs/plugins/readme.markdown b/docs/plugins/readme.markdown new file mode 100644 index 0000000..6e35e29 --- /dev/null +++ b/docs/plugins/readme.markdown @@ -0,0 +1,3 @@ +If you're looking for documentation on Trovebox's various plugins, you're in the right place. + +Questions? Want to write your own plugin? Email our mailing list at openphoto@googlegroups.com.