Adding hello world API docs and updating returnSizes mentions.
This commit is contained in:
Jaisen Mathai
parent
e41e02ae72
commit
a09a7b9d03
8 changed files with 159 additions and 21 deletions
113
documentation/faq/PhotoGeneration.markdown
Normal file
113
documentation/faq/PhotoGeneration.markdown
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
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.
|
||||
|
||||
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
|
||||
67
documentation/faq/Readme.markdown
Normal file
67
documentation/faq/Readme.markdown
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
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/openphoto">Twitter</a> or <a href="mailto:hello@openphoto.me">email</a>.
|
||||
|
||||
### What exactly is OpenPhoto?
|
||||
|
||||
The short answer is that OpenPhoto is a way to store and share your photos without giving up control and ownership of them.
|
||||
|
||||
The long answer is that OpenPhoto consists of two parts: a specification and an implementation.
|
||||
|
||||
The specification is a set of guidelines that define exactly how your photos are stored, how they are accessed and much more.
|
||||
This helps make the entire system open and enables other developers to build functionality on top of your photos.
|
||||
The documentation makes up the majority of the specification.
|
||||
|
||||
The implementation is code which adheres to the specification and provides functionality.
|
||||
The OpenPhoto.me website is an example where the funtionality provided is the ability to store and share photos.
|
||||
Another example would be if a developer created an Instagram like application adhering to the specification.
|
||||
That would be another implementation which provides the functionality of easily sharing photos from your phone with filters.
|
||||
|
||||
----------------------------------------
|
||||
|
||||
### What makes OpenPhoto different from Flickr, Smugmug, iCloud or any other service?
|
||||
|
||||
Normally you pay one company to store your photos and to provide services to share them.
|
||||
This means that you can't do much if they raise their prices, shut down their service or another site comes along.
|
||||
|
||||
These sites may offer APIs but they typically enable addon services and rarely competing services.
|
||||
Your photos are still stored on the company's servers who provide the base service.
|
||||
|
||||
With OpenPhoto you can switch between services, use more than one at a time or stop using the service and continue to have your photos stored.
|
||||
|
||||
----------------------------------------
|
||||
|
||||
### If OpenPhoto is open sourced then why isn't it free?
|
||||
|
||||
For clarity, OpenPhoto is both free and open sourced (FOSS).
|
||||
Typically what you end up paying for is storage from someone like Amazon or Rackspace.
|
||||
|
||||
Amazon offers 5GB of storage for free which means if you don't need any additional space then using OpenPhoto is entirely free.
|
||||
|
||||
----------------------------------------
|
||||
|
||||
### How much does the storage cost?
|
||||
|
||||
It depends on who you use but here are some guidelines.
|
||||
|
||||
1. 20GB of storage on Amazon S3 costs ≈_$2/mo_
|
||||
1. A 250KB photo served up 4,000 times on Amazon S3 costs ≈_$.10/mo_
|
||||
1. A simpleDb database for a personal account is typically _free_
|
||||
|
||||
----------------------------------------
|
||||
|
||||
### When will the OpenPhoto software be completed?
|
||||
|
||||
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 November (2011).
|
||||
|
||||
[guides]: guides/Readme.markdown
|
||||
|
||||
41
documentation/faq/ReturnSizes.markdown
Normal file
41
documentation/faq/ReturnSizes.markdown
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue