From 7ac8e553c5d1b2efe175ebc86bc401d8fd70860c Mon Sep 17 00:00:00 2001 From: sneakypete81 Date: Thu, 28 Mar 2013 10:25:59 +0000 Subject: [PATCH] * Remove email/latitude/longitude * Add actor/owner (although I'm not sure exactly what these mean) * Add delete tag API * Mark create/delete API as "internal" * Create API returns TRUE, not the created tag * Removed update API examples --- docs/api/GetTags.markdown | 13 ++++-- docs/api/PostTagCreate.markdown | 14 ++---- docs/api/PostTagDelete.markdown | 83 +++++++++++++++++++++++++++++++++ docs/api/PostTagUpdate.markdown | 14 ++++-- docs/api/Readme.markdown | 2 + docs/schemas/Tag.markdown | 14 +++--- 6 files changed, 113 insertions(+), 27 deletions(-) create mode 100644 docs/api/PostTagDelete.markdown diff --git a/docs/api/GetTags.markdown b/docs/api/GetTags.markdown index 0ee243e..2314fac 100644 --- a/docs/api/GetTags.markdown +++ b/docs/api/GetTags.markdown @@ -72,23 +72,26 @@ The response is in a standard [response envelope](http://theopenphotoproject.org { "id": "mountain", "count": 1 + "actor": "jaisen@jmathai.com" + "owner": "jaisen@jmathai.com" }, { "id": "jaisen", "count": 10, - "email": "jaisen@jmathai.com" + "actor": "jaisen@jmathai.com" + "owner": "jaisen@jmathai.com" }, { "id": "New York", "count": 9, - "latitude": 12.3456, - "longitude": 78.9012 + "actor": "jaisen@jmathai.com" + "owner": "jaisen@jmathai.com" }, { "id": "Sunnyvale", "count":23 - "latitude": 13.579, - "longitude": 24.68 + "actor": "jaisen@jmathai.com" + "owner": "jaisen@jmathai.com" }, .... ] diff --git a/docs/api/PostTagCreate.markdown b/docs/api/PostTagCreate.markdown index 000fa39..83358ca 100644 --- a/docs/api/PostTagCreate.markdown +++ b/docs/api/PostTagCreate.markdown @@ -18,7 +18,8 @@ Create Tag ### Purpose of the Create Tag API -Use this API to create a tag. +This API is used internally to create a tag. +External applications should use the [Photo Update API](http://theopenphotoproject.org/documentation/api/PostPhotoUpdate) to create tags. ---------------------------------------- @@ -34,9 +35,6 @@ _Authentication: required_ 1. tag (required), The name of the tag to create 1. count (optional), Number of photos which contain this tag -1. email (optional), An email address that corresponds to this tag -1. latitude (optional), _i.e. 34.76_ - A decimal representation of latitude. -1. longitude (optional), _i.e. -87.45_ - A decimal representation of longitude. ---------------------------------------- @@ -63,7 +61,7 @@ The response is in a standard [response envelope](http://theopenphotoproject.org * _message_, A string describing the result. Don't use this for anything but reading. * _code_, _201_ on success -* _result_, A [Tag][Tag] object or FALSE on error +* _result_, TRUE if the tag was successfully created #### Sample @@ -71,11 +69,7 @@ The response is in a standard [response envelope](http://theopenphotoproject.org { "message":"", "code":201, - "result": - { - "id": "mountain", - "count": 0 - } + "result":TRUE } diff --git a/docs/api/PostTagDelete.markdown b/docs/api/PostTagDelete.markdown new file mode 100644 index 0000000..3559c62 --- /dev/null +++ b/docs/api/PostTagDelete.markdown @@ -0,0 +1,83 @@ +Delete Tag +======================= + + +---------------------------------------- + +1. [Purpose][purpose] +1. [Endpoint][endpoint] +1. [Parameters][parameters] +1. [Examples][examples] + * [Command line][example-cli] + * [PHP][example-php] +1. [Response][response] + * [Sample][sample] + +---------------------------------------- + + +### Purpose of the Delete Tag API + +This API is used internally to delete a tag. +External applications should use the [Photo Update API](http://theopenphotoproject.org/documentation/api/PostPhotoUpdate) to delete tags. + +---------------------------------------- + + +### Endpoint + +_Authentication: required_ + + POST /tag/:id/delete.json + + +### Parameters + +---------------------------------------- + + +### Examples + + +#### Command Line (using [openphoto-php][openphoto-php]) + + ./openphoto -p -X POST -h current.trovebox.com -e /tag/sunnyvale/delete.json + + +#### PHP (using [openphoto-php][openphoto-php]) + + $client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $oauthToken, $oauthTokenSecret); + $response = $client->post("/tag/sunnyvale/delete.json"); + +---------------------------------------- + + +### Response + +The response is in a standard [response envelope](http://theopenphotoproject.org/documentation/api/Envelope). + +* _message_, A string describing the result. Don't use this for anything but reading. +* _code_, _201_ on success +* _result_, TRUE if the tag was successfully deleted + + +#### Sample + + { + "message":"", + "code":201, + "result":TRUE + } + + +[Tag]: http://theopenphotoproject.org/documentation/schemas/Tag +[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/photo/openphoto-php + diff --git a/docs/api/PostTagUpdate.markdown b/docs/api/PostTagUpdate.markdown index 88653ea..2d8ebcc 100644 --- a/docs/api/PostTagUpdate.markdown +++ b/docs/api/PostTagUpdate.markdown @@ -7,11 +7,14 @@ Update Tag 1. [Purpose][purpose] 1. [Endpoint][endpoint] 1. [Parameters][parameters] + ---------------------------------------- @@ -32,22 +35,24 @@ _Authentication: required_ ### Parameters -1. count (optional), Number of photos which contain this tag -1. email (optional), An email address that corresponds to this tag -1. latitude (optional), _i.e. 34.76_ - A decimal representation of latitude. -1. longitude (optional), _i.e. -87.45_ - A decimal representation of longitude. +There are not currently any tag attributes that can be updated. ---------------------------------------- + [Tag]: http://theopenphotoproject.org/documentation/schemas/Tag [purpose]: #purpose diff --git a/docs/api/Readme.markdown b/docs/api/Readme.markdown index 414f508..0fe80ab 100644 --- a/docs/api/Readme.markdown +++ b/docs/api/Readme.markdown @@ -51,6 +51,8 @@ Every API endpoint returns a JSON response in a [standard envelope](http://theop Get a user's tags. 1. [POST /tag/create.json](http://theopenphotoproject.org/documentation/api/PostTagCreate) Create a tag for the user. +1. [POST /tag/:id/delete.json](http://theopenphotoproject.org/documentation/api/PostTagDelete) + Delete a tag. 1. [POST /tag/:id/update.json](http://theopenphotoproject.org/documentation/api/PostTagUpdate) Modify meta data for a user's tag. diff --git a/docs/schemas/Tag.markdown b/docs/schemas/Tag.markdown index e035a23..29715fa 100644 --- a/docs/schemas/Tag.markdown +++ b/docs/schemas/Tag.markdown @@ -8,9 +8,9 @@ Schema for a Tag object A Tag object stores information about a specific tag. This includes but is not limited to the number of objects containing this tag. -The Tag objects schema is loose meaning that it can be flexible but at minimum it contains an `id` and `count`. +The Tag objects schema is loose meaning that it can be flexible but at minimum it contains an `id`, `count`, `actor` and `owner`. -For example, the tag `sunnyvale` can have a `latitude` and `longitude` property. +There are not currently any optional tag attributes. ---------------------------------------- @@ -19,9 +19,8 @@ For example, the tag `sunnyvale` can have a `latitude` and `longitude` property. { id: (string), count: (int), - email: (string), - latitude: (float), - longitude: (float) + actor: (string), + owner: (string), } ---------------------------------------- @@ -30,9 +29,8 @@ For example, the tag `sunnyvale` can have a `latitude` and `longitude` property. * id, Base 36 value of a base 10 auto-incremented value * count, The number of objects with this tag - * email, Email address if applicable - * latitude, Latitude if applicable - * longitude, Longitude if applicable + * actor, Email address of the tag actor + * owner, Email address of the tag owner [User]: http://theopenphotoproject.org/documentation/schemas/User [Photo]: http://theopenphotoproject.org/documentation/schemas/Photo