Adding hello world API docs and updating returnSizes mentions.

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]
+
+----------------------------------------
+
+<a name="purpose"></a>
+### 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.
+
+----------------------------------------
+
+<a name="endpoint"></a>
+### Endpoint
+
+_Authentication: optional_
+
+    GET /hello.json
+
+<a name="parameters"></a>
+### Parameters
+
+1.  auth (optional), Pass this in with a value of `true` to test OAuth requests.
+
+----------------------------------------
+
+<a name="examples"></a>
+### Examples
+
+<a name="example-curl"></a>
+#### Command line curl
+
+    curl "http://jmathai.openphoto.me/hello.json"
+    curl "http://jmathai.openphoto.me/hello.json?auth=true"
+
+<a name="example-php"></a>
+#### PHP
+
+    $ch = curl_init('http://jmathai.openphoto.me/hello.json');
+    curl_exec($ch);
+
+----------------------------------------
+
+<a name="response"></a>
+### 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
+
+<a name="sample"></a>
+#### 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
+
+

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
 
 <a name="parameters"></a>
 ### 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

documentation/api/GetPhotos.markdown

@@ -34,9 +34,10 @@ _Authentication: optional_
 <a name="parameters"></a>
 ### 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

documentation/api/GetTags.markdown

@@ -25,9 +25,9 @@ Use this API to get a user's tags.
 <a name="endpoint"></a>
 ### Endpoint
 
-_Authentication: required_
+_Authentication: optional_
 
-    GET /tags.json
+    GET /tags/list.json
 
 <a name="parameters"></a>
 ### Parameters
@@ -42,12 +42,12 @@ _None_
 <a name="example-curl"></a>
 #### Command line curl
 
-    curl "http://jmathai.openphoto.me/tags.json"
+    curl "http://jmathai.openphoto.me/tags/list.json"
 
 <a name="example-php"></a>
 #### PHP
 
-    $ch = curl_init('http://jmathai.openphoto.me/tags.json');
+    $ch = curl_init('http://jmathai.openphoto.me/tags/list.json');
     curl_exec($ch);
 
 ----------------------------------------

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/

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

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 <a href="http://twitter.com/openphotome">Twiter</a> or <a href="mailto:jaisen@openphoto.me">email</a>.
+If you have one which is not on this list send us a message via <a href="http://twitter.com/openphoto">Twitter</a> or <a href="mailto:hello@openphoto.me">email</a>.
 
 ### 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
+

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