We plan to continue to support the legacy version of the API well into 2017 (and later if you let us know), but we do recommend all developers migrate to the new api2 format as your development cycle allows. We strongly recommend that all new recipe and grocery API developers begin with https://api2.bigoven.com
API OVERVIEW
AUTHENTICATION
API PROTOCOL
API DATA
DATA MANAGEMENT
BRANDING, LEGAL & FINANCIAL
Recipe Images
HTTPS versus HTTP images
A copy of all recipe images lives at the root https://bigoven-res.cloudinary.com, and may or may not contain a version number. For instance, a recipe image URL is:
https://bigoven-res.cloudinary.com/image/upload/sweetandsourstickythaiboneless-3a944d.jpg
You can also retrieve the HTTPS equivalent image via a simple string substitution. For any given image URL, you can get the equivalent HTTPS image by fetching the filename (i.e., filename.jpg) and then prepending that filename with:
https://bigoven-res.cloudinary.com/images/upload/
Examples
Image transformations
As you can see from the above URLs, transformations (denoted with t_) can be applied to a recipe image. You can supply the following transformations to get recipe thumbnail sizes:
- t_recipe-1000: 1000px x 1000px
- t_recipe-960: 960px x 960px
- t_recipe-700: 700px x 700px
- t_recipe-640: 640px x 640px
- t_recipe-512: 512px x 512px
- t_recipe-256: 256px x 256px
- t_recipe-200: 200px x 200px
- t_recipe-128: 128px x 128px
- t_recipe-64: 64px x 64px
- t_recipe-48: 48px x 48px
- t_recipe-36: 36px x 36px
Important breaking change (January 2015)
New URLs for derived recipe images
BigOven is moving image hosts to ensure greater scalability, quality and features. With that, our URL structure for accessing transformed (thumbnailed) versions of recipes must change. While we will make efforts to redirect image requests, we cannot guarantee new images and any image transformations to get thumbnails from root image urls will continue to work without code changes by your apps. Recipe images uploaded up to January 1st 2015 will continue to work, but recipe images from January 15th 2015 onward will carry a different URL structure, and you cannot apply the old logic to get the transformed thumbnail recipes - a change to your code is needed, described below.
Some developers have applied "string math" transforms to get resized versions of images, particularly different-sized thumbnails. Those those algorithms need to be updated to also account for the NEW structure.
Example of Legacy-Style URLs
BigOven is moving away from hosting recipe images on:
[www.bigoven.com / mda.bigoven.com / media.bigoven.com]
So, any time you see those domains as hosts for recipe images, you know you're working with a Legacy image url that will likely soon change. URLs come with the following basic styles: Root images could be found at [host]/pics/root-image.jpg, 256x256 thumbnails were at [host]/pics/rs/256/root-image.jpg, 64x64 images where at [host]/pics/rs/64/root-image.jpg, and so on. This has worked for a while, but we have found that this methodology doesn't allow for the scalability that we need. We are moving image hosts.
New Image URLs
New recipe image URLs will generally come down from the API in the newer form of:
https://bigoven-res.cloudinary.com/image/upload/file-name.jpg
You can request (and rely upon) the transformed thumbnails as follows:
- 1024: https://bigoven-res.cloudinary.com/image/upload/t_recipe-1024/file-name.jpg
- 640: https://bigoven-res.cloudinary.com/image/upload/t_recipe-640/file-name.jpg
- 256: https://bigoven-res.cloudinary.com/image/upload/t_recipe-256/file-name.jpg
- 120: https://bigoven-res.cloudinary.com/image/upload/t_recipe-120/file-name.jpg
- 64: https://bigoven-res.cloudinary.com/image/upload/t_recipe-64/file-name.jpg
- original raw image: https://bigoven-res.cloudinary.com/image/upload/file-name.jpg
Note that the transformation algorithm, named "recipe-1024", "recipe-256", etc., is applied in the URL with a t_ (t underscore) parameter, just after the string element "/upload/". This is always the case.
Additionally, for https (secure) connections, you might see your new-style URL delivered as https://bigoven-res.cloudinary.com/image/upload/file-name.jpg -- note the change in hosts (we've moved to Cloudinary for recipe images).
To deal with both legacy and future recipe URLs, BigOven highly recommends that you implement simple string logic that first checks to see which one you're dealing with (legacy or new), and then applies the proper algorithm to get the size you want. The pseudocode for this is essentially:
// psuedocode to correctly transform both old and new recipe image urls
function universalThumbnail(url, thumbSize)
{
if url contains "/pics/" then thumbnailUrlFromLegacyUrl(url, thumbSize)
else thumbnailFromNewUrl(url, thumbSize);
}
// legacy urls look like http://[www|mda|media].bigoven.com/pics/raw-recipe-image.jpg
function thumbnailUrlFromLegacyUrl(url, thumbSize)
{
if (thumbSize is fullSize) {return url.removeFromString(rs/[0-9]*/); }
return url.replace('/pics/','/pics/rs/'+thumbSize+'/');
}
// new-style urls look like https://bigoven-res.cloudinary.com/image/upload/raw-recipe-image.jpg
// or https://bigoven-res.cloudinary.com/image/upload/raw-recipe-image.jpg
// or sometimes https://bigoven-res.cloudinary.com/image/upload/v12039394/raw-recipe-image.jpg
// (with a version number)
// correctly thumbnailing new image urls, you must insert
// "t_recipe-[intSize]/" just after /upload/
// note that [intSize] is restricted to 36, 48, 64, 120, 256, 512, 640, 1024
function thumbnailFromNewUrl(url, thumbSize)
{
if (thumbSize is fullSize) {return url.removeFromString('t_recipe-[0-9]*/');}
return url.replace("/upload/","/upload/t_recipe-"+thumbSize+'/');
}
| Example | Instead of this (it's deprecated!) | Use this for 256x256 |
|---|---|---|
| 1 | https://mda.bigoven.com/pics/rs/256/caesar-salad-ala-steve-3.jpg | https://bigoven-res.cloudinary.com/image/upload/t_recipe-256/caesar-salad-ala-steve-3.jpg |
| 2 | https://media.bigoven.com/pics/classic-eggs-benedict-16.jpg | https://bigoven-res.cloudinary.com/image/upload/t_recipe-256/classic-eggs-benedict-16.jpg |
| 3 | https://www.bigoven.com/pics/classic-eggs-benedict-16.jpg | https://bigoven-res.cloudinary.com/image/upload/t_recipe-256/classic-eggs-benedict-16.jpg |
-- end of breaking changes announcement --
The Recipe Image object refers to an image of a recipe within the BigOven collection. The following methods are supported for the Recipe Image object.
| CREATE | READ | UPDATE | DELETE | |
| Recipe Image | No | Yes | No | No |
Creating a Recipe Image (HTTP POST)
This method is not supported at this time.
Reading a Recipe Image (HTTP GET)
Read all recipe images for a given recipe.
GET https://api.bigoven.com/images?rid={recipeid}
| Parameter | Description | Required? |
| rid | Primary key(ID) of recipe. | Yes |
Updating a Recipe Image (HTTP PUT)
This method is not supported at this time.
Deleting a Recipe Image (HTTP DELETE)
This method is not supported at this time.