yetangitu/photo-front
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Documenting photo generation and returnSizes.

Browse source
This commit is contained in:
Jaisen Mathai 2011-08-18 01:11:36 -07:00
parent 934bc42485
commit b9e91df9b7
4 changed files with 122 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

110
documentation/PhotoGeneration.markdown Normal file
View file

@ -0,0 +1,110 @@
Open Photo API / Photo Upload
=======================
#### OpenPhoto, a photo service for the masses
----------------------------------------
### Overview of how and when versions of photos are generated
By default, when a photo is uploaded there are two versions of that photo which are stored. The original version (`pathOriginal`) and a slightly lower resolution version (`pathBase`).
The API is capable of returning URLs for any size version of every photo. This is acheived by passing in a parameter named `returnSizes` to the [GET Photos][GetPhotos] and [GET Photo][GetPhoto] APIs. This ensures that the response for the photo(s) will include a URL for the size(s) you specify. Here is an example.
curl "http://current.openphoto.me/photo/63.json?returnSizes=123x123"
This call returns the following response.
{
"code" : 200,
"message" : "Photo 63",
"result" : {
"appId" : "current.openphoto.me",
"creativeCommons" : "BY-NC",
"dateTaken" : "1313010850",
"dateTakenDay" : "10",
"dateTakenMonth" : "08",
"dateTakenYear" : "2011",
"dateUploaded" : "1313010853",
"dateUploadedDay" : "10",
"dateUploadedMonth" : "08",
"dateUploadedYear" : "2011",
"description" : "",
"exifCameraMake" : "",
"exifCameraModel" : "",
"hash" : "20d64642f09befc4004c22269e698e6e43475963",
"height" : "1936",
"host" : "opmecurrent.s3.amazonaws.com",
"id" : "63",
"latitude" : "",
"longitude" : "",
"path123x123" : "http://current.openphoto.me/photo/63/create/1a7f0/123x123.jpg",
"path200x200" : "http://opmecurrent.s3.amazonaws.com/custom/201108/1313010849-opmeTbrBki_200x200.jpg",
"pathBase" : "/base/201108/1313010849-opmeTbrBki.jpg",
"pathOriginal" : "/original/201108/1313010849-opmeTbrBki.jpg",
"permission" : "1",
"size" : "1513",
"status" : "1",
"tags" : [ ],
"title" : "Gulf Shores, AL",
"views" : "0",
"width" : "2592"
}
}
The most important keys in the response are `path123x123` and `path200x200`. Either of these URLs will correctly render the photo in the respective size. Notice, however, that the `path123x123` hostname is different from `path200x200`. This is important because this implies that a _123x123_ version of the photo doesn't exist and the API host needs to generate it. The following url will generate the correct version of the photo, store it to the proper file system, saves it to the database and returns it with a content-type of _image/jpeg_.
http://current.openphoto.me/photo/63/create/1a7f0/123x123.jpg
It's important to realize that the photo isn't generated and stored until this URL is called. This typically happens when the browser tries to display this photo. Once that has happened then the _123x123_ version exists both in the database and file system and calling the same API again returns a different URL for `path123x123`.
{
"code" : 200,
"message" : "Photo 63",
"result" : {
"appId" : "current.openphoto.me",
"creativeCommons" : "BY-NC",
"dateTaken" : "1313010850",
"dateTakenDay" : "10",
"dateTakenMonth" : "08",
"dateTakenYear" : "2011",
"dateUploaded" : "1313010853",
"dateUploadedDay" : "10",
"dateUploadedMonth" : "08",
"dateUploadedYear" : "2011",
"description" : "",
"exifCameraMake" : "",
"exifCameraModel" : "",
"hash" : "20d64642f09befc4004c22269e698e6e43475963",
"height" : "1936",
"host" : "opmecurrent.s3.amazonaws.com",
"id" : "63",
"latitude" : "",
"longitude" : "",
"path123x123" : "http://opmecurrent.s3.amazonaws.com/custom/201108/1313010849-opmeTbrBki_123x123.jpg",
"path200x200" : "http://opmecurrent.s3.amazonaws.com/custom/201108/1313010849-opmeTbrBki_200x200.jpg",
"pathBase" : "/base/201108/1313010849-opmeTbrBki.jpg",
"pathOriginal" : "/original/201108/1313010849-opmeTbrBki.jpg",
"permission" : "1",
"size" : "1513",
"status" : "1",
"tags" : [ ],
"title" : "Gulf Shores, AL",
"views" : "0",
"width" : "2592"
}
}
The URL for `path123x123` now points to a static resource.
You can specify multiple sizes for the `returnSizes` delimited by commas.
curl "http://current.openphoto.me/photo/63.json?returnSizes=123x123,300x300xBW"
### Understanding options for returnSizes
The `returnSizes` parameter takes values in the form of _WxH[[xA]xB]_ which means it starts with a numeric _width_ and _height_. The most simple form is limited to specifying just a _width_ and _height_. This looks like `200x200` or `125x300`.
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.
[GetPhotos]: api/GetPhotos.markdown
[GetPhoto]: api/GetPhoto.markdown

8
documentation/api/GetPhoto.markdown
View file

@ -18,6 +18,9 @@ Open Photo API / Get Photo
<a name="purpose"></a>
### Purpose of the Get Photo API
Use this API to get a single of photo for a user.
_NOTE:_ Always pass in the `returnSizes` parameter for sizes you plan on using. It's the only way to guarantee that a URL for that size will be present in the response. See [Photo Generation][photogeneration] for details.
----------------------------------------
@ -31,7 +34,7 @@ _Authentication: optional_
<a name="parameters"></a>
### Parameters
_None_
1. returnSizes (optional), The photo sizes you'd like in the response. Specify every size you plan on using.
----------------------------------------
@ -107,5 +110,4 @@ The response is in a standard [response envelope][Envelope].
[example-php]: #example-php
[response]: #response
[sample]: #sample
[photogeneration]: ../PhotoGeneration.markdown

8
documentation/api/GetPhotos.markdown
View file

@ -18,6 +18,9 @@ Open Photo API / Get Photos
<a name="purpose"></a>
### Purpose of the Get Photos API
Use this API to get a set of photos for a user.
_NOTE:_ Always pass in the `returnSizes` parameter for sizes you plan on using. It's the only way to guarantee that a URL for that size will be present in the response. See [Photo Generation][photogeneration] for details.
----------------------------------------
@ -31,6 +34,7 @@ _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. 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.
@ -135,7 +139,7 @@ The response is in a standard [response envelope][Envelope].
}
[Envelope]: api/Envelope.markdown
[Photo]: https://github.com/openphoto/frontend/blob/master/documentation/schemas/Photo.markdown
[Photo]: schemas/Photo.markdown
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters
@ -144,4 +148,4 @@ The response is in a standard [response envelope][Envelope].
[example-php]: #example-php
[response]: #response
[sample]: #sample
[photogeneration]: ../PhotoGeneration.markdown

2
documentation/api/PostPhotoUpload.markdown
View file

@ -124,7 +124,7 @@ The response is in a standard [response envelope][Envelope].
}
[Envelope]: api/Envelope.markdown
[Photo]: https://github.com/openphoto/frontend/blob/master/documentation/schemas/Photo.markdown
[Photo]: schemas/Photo.markdown
[purpose]: #purpose
[endpoint]: #endpoint
[parameters]: #parameters