Updating documentation for all remaining API endpoints.

Closes Gh-180

Readme.markdown

@@ -1,12 +1,16 @@
-OpenPhoto
-=======================
-#### OpenPhoto - A free, hosted, portable and open source photo sharing service
+<img src="frontend/raw/master/files/creative/logo.png" style="width:234px; height:43px; margin:auto;">
 
-----------------------------------------
 
 ### What is OpenPhoto?
 
-#### OpenPhoto is a way to store and share your photos while keeping control and ownership of them
+1.  [FAQ][faq], Answers to the most common questions.
+1.  [API][api], Documentation to get started building applications on OpenPhoto.
+1.  [Schemas][schemas], Description of what the different objects in OpenPhoto look like (i.e. a photo or a comment).
+1.  [Guides][guides], Detailed guides to help you get the OpenPhoto software installed on various systems.
+
+----------------------------------------
+
+### How does OpenPhoto work?
 
 OpenPhoto works similarly to Flickr, Smugmug and other photo sharing services with one major difference: you retain ownership and give OpenPhoto access to use them.
 All photos, tags and comments are stored in your personal cloud accounts with companies like Amazon, Rackspace or Google. 
@@ -43,4 +47,7 @@ There are importing tools available to make the switch easy.
 [aws]: http://aws.amazon.com/
 [s3]: http://aws.amazon.com/s3/
 [simpledb]: http://aws.amazon.com/simpledb/
-[FAQ]: frontend/documentation/faq/Faq.markdown
+[api]: documentation/api/Api.markdown
+[faq]: documentation/faq/Faq.markdown
+[schemas]: documentation/schemas/Schemas.markdown
+[guides]: documentation/guides/Guides.markdown

documentation/api/Api.markdown

@@ -67,24 +67,12 @@ Every API endpoint returns a JSON response in a [standard envelope][Envelope].
     Update a group.
 
 #### Webhook endpoints
+1.  [POST /webhook/subscribe][PostWebHookSubscribe]
+    Update an eixsting webhook.
 1.  [GET /webhook/:id/view.json][GetWebhook]
     Get a user's webhook by id.
-1.  [GET /webhooks/list.json][GetWebhooks]
-    An internal private API to list the user's webhooks.
-1.  [POST /webhook/create.json][PostWebhookCreate]
-    Create a new webhook for the user.
 1.  [POST /webhook/:id/delete.json][PostWebHookDelete]
     Delete an existing webhook.
-1.  [POST /webhook/:id/update.json][PostWebHookUpdate]
-    Update an eixsting webhook.
-
-<!--
-;[PostWebhookCreate]: PostWebhookCreate.markdown
-;[PostWebhookDelete]: PostWebhookDelete.markdown
-;[PostWebhookUpdate]: PostWebhookUpdate.markdown
-;[GetWebhook]: GetWebhook.markdown
-;[GetWebhooks]: GetWebhooks.markdown
--->
 
 [Envelope]: Envelope.markdown
 [GetHelloWorld]: GetHelloWorld.markdown
@@ -104,5 +92,8 @@ Every API endpoint returns a JSON response in a [standard envelope][Envelope].
 [PostGroupCreate]: PostGroupCreate.markdown
 [PostGroupUpdate]: PostGroupUpdate.markdown
 [PostGroupDelete]: PostGroupDelete.markdown
+[GetWebhook]: GetWebhook.markdown
+[PostWebhookSubscribe]: PostWebHookSubscribe.markdown
+[PostWebhookDelete]: PostWebhookDelete.markdown
 [authentication]: Authentication.markdown
 [oauth1.0a]: http://oauth.net/core/1.0a/

documentation/api/GetGroup.markdown

@@ -81,7 +81,7 @@ The response is in a standard [response envelope][Envelope].
     }
 
 [Envelope]: Envelope.markdown
-[Photo]: ../schemas/Group.markdown
+[Group]: ../schemas/Group.markdown
 [purpose]: #purpose
 [endpoint]: #endpoint
 [parameters]: #parameters

documentation/api/GetGroups.markdown

@@ -103,7 +103,7 @@ The response is in a standard [response envelope][Envelope].
     }
 
 [Envelope]: Envelope.markdown
-[Photo]: ../schemas/Group.markdown
+[Group]: ../schemas/Group.markdown
 [purpose]: #purpose
 [endpoint]: #endpoint
 [parameters]: #parameters

documentation/api/GetWebhook.markdown

@@ -1 +1,92 @@
-Not yet documented
+Open Photo API / Get Photo
+=======================
+#### OpenPhoto, a photo service for the masses
+
+----------------------------------------
+
+1. [Purpose][purpose]
+1. [Endpoint][endpoint]
+1. [Parameters][parameters]
+1. [Examples][examples]
+  * [Command line][example-cli]
+  * [PHP][example-php]
+1. [Response][response]
+  * [Sample][sample]
+
+----------------------------------------
+
+<a name="purpose"></a>
+### Purpose of the GET Webhook API
+
+Use this API to get a user's Webhook.
+
+----------------------------------------
+
+<a name="endpoint"></a>
+### Endpoint
+
+_Authentication: required_
+
+    GET /webhook/:id/view.json
+
+<a name="parameters"></a>
+### Parameters
+
+_None_
+
+----------------------------------------
+
+<a name="examples"></a>
+### Examples
+
+<a name="example-cli"></a>
+#### Command Line (using [openphoto-php][openphoto-php])
+
+    source secrets.sh
+    ./openphoto -p -h current.openphoto.me -e /webhook/abcdefghijklmnopqrstuvwxyz/view.json
+
+<a name="example-php"></a>
+#### PHP (using [openphoto-php][openphoto-php])
+
+    $client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
+    $response = $client->get("/webhook/abcdefghijklmnopqrstuvwxyz/view.json");
+
+----------------------------------------
+
+<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_, A [Webhook][Webhook] object
+
+<a name="sample"></a>
+#### Sample
+
+    {
+      "message" : "Your group",
+      "code" : 200,
+      "result" : {
+        id: "abcdefghijklmnopqrstuvwxyz",
+        appId: "current.openphoto.me",
+        callback: "http://somehost.com/somepath",
+        topic: "photo.upload",
+        verifyToken: "qazwsxedcrfvz",
+        challenge: "plmoknijbuhv",
+        secret: "rfvtgbyhn"
+      }
+    }
+
+[Envelope]: Envelope.markdown
+[Webhook]: ../schemas/Webhook.markdown
+[purpose]: #purpose
+[endpoint]: #endpoint
+[parameters]: #parameters
+[examples]: #examples
+[example-cli]: #example-cli
+[example-php]: #example-php
+[response]: #response
+[sample]: #sample
+[openphoto-php]: https://github.com/openphoto/openphoto-php

documentation/api/PostWebhookCreate.markdown

@@ -1 +0,0 @@
-Not yet documented

documentation/api/PostWebhookDelete.markdown

@@ -1 +1,86 @@
-Not yet documented
+Open Photo API / Get Photo
+=======================
+#### OpenPhoto, a photo service for the masses
+
+----------------------------------------
+
+1. [Purpose][purpose]
+1. [Endpoint][endpoint]
+1. [Parameters][parameters]
+1. [Examples][examples]
+  * [Command line][example-cli]
+  * [PHP][example-php]
+1. [Response][response]
+  * [Sample][sample]
+
+----------------------------------------
+
+<a name="purpose"></a>
+### Purpose of the POST Webhook delete API
+
+Use this API to delete an existing webhook for a user.
+
+----------------------------------------
+
+<a name="endpoint"></a>
+### Endpoint
+
+_Authentication: required_
+
+    POST /webhook/:id/delete.json
+
+<a name="parameters"></a>
+### Parameters
+
+_None_
+
+----------------------------------------
+
+<a name="examples"></a>
+### Examples
+
+<a name="example-cli"></a>
+#### Command Line (using [openphoto-php][openphoto-php])
+
+    source secrets.sh
+    ./openphoto -p -X POST -h current.openphoto.me -e /webhook/abcdefghijklmnopqrstuvwxyz/delete.json
+
+<a name="example-php"></a>
+#### PHP (using [openphoto-php][openphoto-php])
+
+    $client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret);
+    $response = $client->post('/webhook/abcdefghijklmnopqrstuvwxyz/delete.json');
+
+----------------------------------------
+
+<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_, A boolean
+
+<a name="sample"></a>
+#### Sample
+
+    {
+      "message" : "Webhook deleted successfully",
+      "code" : 200,
+      "result" : true
+    }
+
+[Envelope]: Envelope.markdown
+[Webhook]: ../schemas/Webhook.markdown
+[webhookverification]: ../faq/WebhookVerification.markdown
+[purpose]: #purpose
+[endpoint]: #endpoint
+[parameters]: #parameters
+[examples]: #examples
+[example-cli]: #example-cli
+[example-php]: #example-php
+[response]: #response
+[sample]: #sample
+[openphoto-php]: https://github.com/openphoto/openphoto-php
+

documentation/api/PostWebhookSubscribe.markdown

@@ -0,0 +1,53 @@
+Open Photo API / Get Photo
+=======================
+#### OpenPhoto, a photo service for the masses
+
+----------------------------------------
+
+1. [Purpose][purpose]
+1. [Endpoint][endpoint]
+1. [Parameters][parameters]
+1. [Examples][examples]
+  * [Command line][example-cli]
+  * [PHP][example-php]
+1. [Response][response]
+  * [Sample][sample]
+
+----------------------------------------
+
+<a name="purpose"></a>
+### Purpose of the POST Webhook create API
+
+Use this API to create a new webhook for a user.
+
+This API differs from our others in that it's both interactive and does not return a [Standard Envelope][Envelope]. These are the steps required to complete a webhook subscription.
+
+<a name="verification"></a>
+1.  The consumer _(you)_ makes a POST request to the provider _(the API host)_ to `http://apihost.com/webhook/subscribe` with the <a href="#">required parameters</a>.
+1.  The provider makes a GET request back to your `callback` URL passing along a `mode`, `topic`, and `challenge` parameter. A `verifyToken` parameter is passed back if originally supplied.
+1.  The consumer must validate that the subscription was intended (typically using the `verifyToken`) and print out the `challenge` value with a HTTP 200 response code.
+1.  If the consumer response is a HTTP 200 and the content body was equal to `challenge` then the provider completes the subscription.
+
+----------------------------------------
+
+<a name="endpoint"></a>
+### Endpoint
+
+_Authentication: required_
+
+    POST /webhook/create.json
+
+<a name="parameters"></a>
+### Parameters
+
+1.  callback (required), A URL to POST to. This also needs to handle GET calls for the <a href="#verification">verification process</a>.
+1.  topic (required), _i.e. photo.upload_ - The topic which you'd like to subscribe to.
+1.  mode (required), Only _sync_ is supported at this time.
+1.  verifyToken (optional), A provider generated string to which is passed back as part of the <a href="#verification">verification process</a>.
+
+----------------------------------------
+
+[Envelope]: Envelope.markdown
+[purpose]: #purpose
+[endpoint]: #endpoint
+[parameters]: #parameters

documentation/api/PostWebhookUpdate.markdown

@@ -1 +0,0 @@
-Not yet documented

src/libraries/routes-api.php

@@ -77,6 +77,6 @@ getApi()->get('/groups/list.json', array('ApiGroupController', 'list_'), EpiApi:
  */
 getApi()->post('/webhook/create.json', array('ApiWebhookController', 'create'), EpiApi::internal);
 getApi()->post('/webhook/([a-zA-Z0-9]+)/delete.json', array('ApiWebhookController', 'delete'), EpiApi::external);
-getApi()->post('/webhook/([a-zA-Z0-9]+)/update.json', array('ApiWebhookController', 'update'), EpiApi::external);
+getApi()->post('/webhook/([a-zA-Z0-9]+)/update.json', array('ApiWebhookController', 'update'), EpiApi::internal);
 getApi()->get('/webhook/([a-zA-Z0-9]+)/view.json', array('ApiWebhookController', 'view'), EpiApi::external);
 getApi()->get('/webhooks/?(.*)?/list.json', array('ApiWebhookController', 'list_'), EpiApi::internal);