From a09a7b9d03a58f4bdf7adbb287d9a0293e12c8ba Mon Sep 17 00:00:00 2001 From: Jaisen Mathai Date: Mon, 3 Oct 2011 13:31:24 -0700 Subject: [PATCH] Adding hello world API docs and updating returnSizes mentions. --- documentation/api/GetHelloWorld.markdown | 87 +++++++++++++++++++ documentation/api/GetPhoto.markdown | 7 +- documentation/api/GetPhotos.markdown | 8 +- documentation/api/GetTags.markdown | 8 +- documentation/api/Readme.markdown | 15 ++-- .../{ => faq}/PhotoGeneration.markdown | 3 + .../{FAQ.markdown => faq/Readme.markdown} | 11 +-- documentation/faq/ReturnSizes.markdown | 41 +++++++++ 8 files changed, 159 insertions(+), 21 deletions(-) create mode 100644 documentation/api/GetHelloWorld.markdown rename documentation/{ => faq}/PhotoGeneration.markdown (97%) rename documentation/{FAQ.markdown => faq/Readme.markdown} (86%) create mode 100644 documentation/faq/ReturnSizes.markdown diff --git a/documentation/api/GetHelloWorld.markdown b/documentation/api/GetHelloWorld.markdown new file mode 100644 index 00000000..712a27b2 --- /dev/null +++ b/documentation/api/GetHelloWorld.markdown @@ -0,0 +1,87 @@ +Open Photo API / Hello World +======================= +#### OpenPhoto, a photo service for the masses + +---------------------------------------- + +1. [Purpose][purpose] +1. [Endpoint][endpoint] +1. [Parameters][parameters] +1. [Examples][examples] + * [Curl][example-curl] + * [PHP][example-php] +1. [Response][response] + * [Sample][sample] + +---------------------------------------- + + +### Purpose of the Get Hello World API + +This endpoint is used to test connectivity and/or authentication. Any parameters passed in the query string are returned in the response. + +---------------------------------------- + + +### Endpoint + +_Authentication: optional_ + + GET /hello.json + + +### Parameters + +1. auth (optional), Pass this in with a value of `true` to test OAuth requests. + +---------------------------------------- + + +### Examples + + +#### Command line curl + + curl "http://jmathai.openphoto.me/hello.json" + curl "http://jmathai.openphoto.me/hello.json?auth=true" + + +#### PHP + + $ch = curl_init('http://jmathai.openphoto.me/hello.json'); + curl_exec($ch); + +---------------------------------------- + + +### Response + +The response is in a standard [response envelope][Envelope]. + +* _message_, A string describing the result. Don't use this for anything but reading. +* _code_, _200_ on success +* _result_, An array of [Tag][Tag] objects + + +#### Sample + + { + "message":"Hello, world!", + "code":200, + "result": + { + "__route__":"\/hello.json" + } + } + +[Envelope]: api/Envelope.markdown +[purpose]: #purpose +[endpoint]: #endpoint +[parameters]: #parameters +[examples]: #examples +[example-curl]: #example-curl +[example-php]: #example-php +[response]: #response +[sample]: #sample + + diff --git a/documentation/api/GetPhoto.markdown b/documentation/api/GetPhoto.markdown index e8f5a9b1..08236253 100644 --- a/documentation/api/GetPhoto.markdown +++ b/documentation/api/GetPhoto.markdown @@ -29,12 +29,12 @@ _NOTE:_ Always pass in the `returnSizes` parameter for sizes you plan on using. _Authentication: optional_ - GET /photo/:id.json + GET /photo/:id/view.json ### Parameters -1. returnSizes (optional), The photo sizes you'd like in the response. Specify every size you plan on using. +1. returnSizes (optional), The photo sizes you'd like in the response. Specify every size you plan on using. [Docs for this parameter][ReturnSizes] ---------------------------------------- @@ -110,4 +110,5 @@ The response is in a standard [response envelope][Envelope]. [example-php]: #example-php [response]: #response [sample]: #sample -[photogeneration]: ../PhotoGeneration.markdown +[photogeneration]: faq/PhotoGeneration.markdown +[ReturnSizes]: faq/ReturnSizes.markdown diff --git a/documentation/api/GetPhotos.markdown b/documentation/api/GetPhotos.markdown index c405be48..d20c3b2b 100644 --- a/documentation/api/GetPhotos.markdown +++ b/documentation/api/GetPhotos.markdown @@ -34,9 +34,10 @@ _Authentication: optional_ ### Parameters -1. returnSizes (optional), The photo sizes you'd like in the response. Specify every size you plan on using. +1. returnSizes (optional), The photo sizes you'd like in the response. Specify every size you plan on using. [Docs for this parameter][ReturnSizes] +1. pageSize (optional), Number of photos to return per request. 1. page (optional), Page number when browsing through photos. Starts at 1. -1. tags (optional), _i.e. dog,cat_ - A comma delimited string of alpha numeric strings. +1. tags (optional), _i.e. dog,cat_ - A comma delimited string of strings. ---------------------------------------- @@ -142,4 +143,5 @@ The response is in a standard [response envelope][Envelope]. [example-php]: #example-php [response]: #response [sample]: #sample -[photogeneration]: ../PhotoGeneration.markdown +[photogeneration]: faq/PhotoGeneration.markdown +[ReturnSizes]: faq/ReturnSizes.markdown diff --git a/documentation/api/GetTags.markdown b/documentation/api/GetTags.markdown index 4cd041a2..73a6a9a4 100644 --- a/documentation/api/GetTags.markdown +++ b/documentation/api/GetTags.markdown @@ -25,9 +25,9 @@ Use this API to get a user's tags. ### Endpoint -_Authentication: required_ +_Authentication: optional_ - GET /tags.json + GET /tags/list.json ### Parameters @@ -42,12 +42,12 @@ _None_ #### Command line curl - curl "http://jmathai.openphoto.me/tags.json" + curl "http://jmathai.openphoto.me/tags/list.json" #### PHP - $ch = curl_init('http://jmathai.openphoto.me/tags.json'); + $ch = curl_init('http://jmathai.openphoto.me/tags/list.json'); curl_exec($ch); ---------------------------------------- diff --git a/documentation/api/Readme.markdown b/documentation/api/Readme.markdown index a4355571..14110056 100644 --- a/documentation/api/Readme.markdown +++ b/documentation/api/Readme.markdown @@ -6,7 +6,7 @@ Open Photo API ### How do I authenticate? -The Open Photo API uses [OAuth2][oauth2] for authentication. See the complete [guide on authentication][authentication] for details. +The Open Photo API uses [OAuth1.0a][oauth1.0a] for authentication. See the complete [guide on authentication][authentication] for details. _NOTE:_ OAuth2 isn't yet enabled. @@ -24,22 +24,25 @@ Every API endpoint returns a JSON response in a [standard envelope][Envelope]. ### API Endpoints -1. [GET /photos.json][GetPhotos] +1. [GET /hello.json][GetHelloWorld] + Test endpoint. +1. [GET /photos/list.json][GetPhotos] Get a list of the user's photos. -1. [GET /photo/:id.json][GetPhoto] +1. [GET /photo/:id/view.json][GetPhoto] Get a user's photo. 1. [POST /photo/upload.json][PostPhotoUpload] Upload a new photo. -1. [GET /tags.json][GetTags] +1. [GET /tags/list.json][GetTags] Get a user's tags. -1. [POST /tag/:id.json][PostTag] +1. [POST /tag/:id/update.json][PostTag] Modify meta data for a user's tag. [Envelope]: api/Envelope.markdown +[GetHelloWorld]: api/GetHelloWorld.markdown [GetPhotos]: api/GetPhotos.markdown [GetPhoto]: api/GetPhoto.markdown [GetTags]: api/GetTags.markdown [PostPhotoUpload]: api/PostPhotoUpload.markdown [PostTag]: api/PostTag.markdown [authentication]: api/Authentication.markdown -[oauth2]: http://wiki.oauth.net/w/page/25236487/OAuth-2 +[oauth1.0a]: http://oauth.net/core/1.0a/ diff --git a/documentation/PhotoGeneration.markdown b/documentation/faq/PhotoGeneration.markdown similarity index 97% rename from documentation/PhotoGeneration.markdown rename to documentation/faq/PhotoGeneration.markdown index 1b766736..4cb9e63f 100644 --- a/documentation/PhotoGeneration.markdown +++ b/documentation/faq/PhotoGeneration.markdown @@ -106,5 +106,8 @@ The `returnSizes` parameter takes values in the form of _WxH[[xA]xB]_ which mean Additional options include `CR` and `BW`. `CR` tells the API to crop the photo to be exactly _width_ by _height_. It does a center crop and minimizes the portion of the photo that is cropped. `BW` applies a greyscale filter to the photo. `100x100xCRxBW` means the photo will have a key of `path100x100xCRxBW` and will be exactly _100_ by _100_, cropped and greyscale. +For more information on the `returnSizes` parameter see our [documentation on returnSizes][ReturnSizes]. + [GetPhotos]: api/GetPhotos.markdown [GetPhoto]: api/GetPhoto.markdown +[ReturnSizes]: faq/ReturnSizes.markdown diff --git a/documentation/FAQ.markdown b/documentation/faq/Readme.markdown similarity index 86% rename from documentation/FAQ.markdown rename to documentation/faq/Readme.markdown index a8831ab6..a8da2544 100644 --- a/documentation/FAQ.markdown +++ b/documentation/faq/Readme.markdown @@ -3,7 +3,7 @@ Documentation #### OpenPhoto, a photo service for the masses This is a list of common questions that people have about OpenPhoto. -If you have one which is not on this list send us a message via Twiter or email. +If you have one which is not on this list send us a message via Twitter or email. ### What exactly is OpenPhoto? @@ -55,12 +55,13 @@ It depends on who you use but here are some guidelines. ### When will the OpenPhoto software be completed? -The initial version should be ready by the end of July (2011). -This will allow anyone to download the source code and set it up on their server. -We'll be working to make that easier by partnering with sites like dotCloud and providing ready to use AMIs for AWS or Rackspace. +You can set up the OpenPhoto software using [any of the guides][guides]. ---------------------------------------- ### When will the hosted version of OpenPhoto be available? -We are aiming to have it ready by the end of August (2011). +We are aiming to have it ready by the end of November (2011). + +[guides]: guides/Readme.markdown + diff --git a/documentation/faq/ReturnSizes.markdown b/documentation/faq/ReturnSizes.markdown new file mode 100644 index 00000000..cc937722 --- /dev/null +++ b/documentation/faq/ReturnSizes.markdown @@ -0,0 +1,41 @@ +Open Photo API / Photo Upload +======================= +#### OpenPhoto, a photo service for the masses + +---------------------------------------- + +### Understanding the `returnSizes` parameter and how to use it +For the [GET /photo/view.json][GetPhoto] [GET /photos/list.json][GetPhotos] you can pass in an optional `returnSizes` parameter. +If you need a path to a photo then you'll want to make sure you pass this parameter in else your response won't contain any URLs. + +We also have a more detailed look at how [photos are generated][photogeneration]. + +### Specifying the width and height of photos you want +The first decision you need to make is the size or sizes of photos you want in the response. +You'll specify this as the initial part of the `returnSizes` parameter. + +If you want a single size for the photo of width `W` and height `H` then you will want to use the following. + + returnSizes=WxH + +If you want multiple sizes for the photo of widths `W1` and `W2` and heights `H1` and `H2` then use the following. + + returnSizes=W1xH1,W2xH2 + +#### Maintaining aspect ratio and cropping +By default the aspect ratio of every photo is maintained. +That means if you request a `200x200` version of a photo that's originally `800x600` then the resulting image will be _200px_ wide and _150px_ tall. + + +If you want the same photo to be exactly _200px_ by _200px_ then you can add an optional value to `returnSizes`. + + returnSizes=200x200xCR + +Adding `xCR` means that the photo will be exactly _200px_ by _200px_ and cropped from the center retaining as much of the photo as possible. + +### Accessing the paths in the response +The name of the URL attribute in the response is, by convention, `pathWxH` where `WxH` is the value passed in to returnSizes. + +[GetPhoto]: api/GetPhoto.markdown +[GetPhotos]: api/GetPhotos.markdown +[photogeneration]: faq/PhotoGeneration.markdown