API DOC the Campbell’s Kitchen API This API documentation is provided to help with the ideation process by outlining its functionality. Developers of the top thirty ideas will get access to the actual Campbell’s Kitchen API from February 11 to March 4, 2013 to develop and submit a working prototype. Using the Campbell’s Kitchen API, your application can: • Search through thousands of recipes by key ingredients, product, meal occasions, cuisine, total time, and more. • Display recipes in detail, which includes high quality food photography and recipe ratings • Get recipe reviews, and detailed ingredient information. AUTHENTICATION If you are selected to participate in Campbell’s Hack The Kitchen program, you will be issued a unique API token required to use to access the API. This API token is then required as part of each URL request made. For example: GET /recipes/recipe/1234567 HTTP/1.1 Host: www.api.campbellskitchen.com Cookie: apikey=F0E71887BAE13905 Calls that do not contain the API token named “apikey”, or whose API token is not valid, will receive a “HTTP 401 UNAUTHORIZED” response status code. With a valid key, successful calls will be sent a “HTTP 200 (OK)” return code, along with their results. Please note: • Tokens timeout after 20 minutes if not used • The timeout is reset with each use of a token • The token expires upon logout • One token assigned per user Everything in the Kitchen through API DATA The Campbell’s Kitchen collection of recipes is growing and made with products from the Campbell’s family of brands that people love. Get Recipe The Recipe object refers to the collection of Campbell’s Kitchen recipes. At the present time, we only support the Read method (HTTP GET) for the Recipe object. Each call checks to see if the token is valid, not expired, and the associated user is below their API daily limit. Get Single Recipe, Basic Results A Campbell’s Kitchen API request is an HTTP URL of the following form: http:// api.campbellskitchen.com/api/recipe/1234567?format=xml& token=0123456789ABCDEF Required Parameters: • Multiple recipe IDs separated by pipe ( | ) • A valid token Optional Parameters: • Format – xml or json (default xml) Get Multiple Recipes Request A Campbell’s Kitchen API request is an HTTP URL of the following form: http://api.campbellskitchen.com/api/recipe/1234567|7654321|7776666|5553333?format=xml&token=0123456789ABCDEF Required Parameters: • Multiple recipe IDs separated by pipe ( | ) • Token – a valid token Optional Parameters: • Format – xml or json (default xml) Recipe images A comprehensive library of professionally shot food photography is available in most cases; however, for those recipes without an associated image, a placeholder image will be used. The Recipe Image object refers to an image of a recipe within the Campbell’s Kitchen collection. The following methods are supported for the Recipe Image object. At the present time, we only support the Read method (HTTP GET) for the Recipe object. Read all recipe images for a given recipe GET http://api.campbellskitchen.com/images?rid={recipeid} Parameter DescriptionRequired Screen resolutionImage Size rid Primary key (ID) of recipe. Yes 420 x 360 72 DPI Ratings & Reviews Literally thousands of reader-generated recipe reviews and ratings are at your disposal. Get All Recipe Reviews A Campbell’s Kitchen API request is an HTTP URL of the following form: http:// api.campbellskitchen.com/api/recipereviews/1234567?format=xml&token=0123456789ABCDEF Required Parameters: rated by pipe ( | ) • Multiple recipe IDs separated by pipe ( | ) • Token – a valid token • Token – a valid token Basic Recipe Search Each call checks to see if the token is valid and has not expired, and the associated user is below their daily API usage limit. Search Category A Campbell’s Kitchen API request is an HTTP URL of the following form: http:// api.campbellskitchen.com/api/search?category=1&format=xml&token=0123456789ABCDEF Required Parameters: • Category – the ID of the category to return • Token – a valid token Optional Parameters: • Format – XML, JSON (default XML) • Start – start at record number (default 1) • Total – the total number of results to return (defaults 10) Recipe Search Results Extensive search capabilities filtered by key ingredients, product, meal occasions, cuisine, total time, and more. • API responses are in JSON or XML. • API endpoints accept GET and POST requests as per the API specification. If you use POST requests, your API token, and other request parameters will be sent in the request body, not in the URL itself. Versioning API versioning (URIs) Over time, as new features are introduced, the recipe API will expand and new URIs will be introduced. In order to preserve legacy usage, the URI of existing APIs will not change. We will attempt to keep the accessible address of the services the same long into the future. API versioning (schema) Making a call to the Recipe API will often include parameters with the request or posting data along with it. Any new parameters added will be made optional, and logical defaults will be chosen for them. Posted data will also support both a legacy format and the new format, with logical defaults given. API Protocol Usage Throttling Without a special agreement with Campbell each account will be limited to 10000 API calls (GET) per day. This is to ensure resources are shared fairly among all developers. Any abuse of this privilege may result in revocation of your license. When the daily limit is reached, the server will begin sending a “HTTP 401 UNAUTHORIZED” response status code. The daily limit is reset at midnight Eastern US time. Please note: Upon request, your usage needs can be reviewed and your limit can be increased if approved. Response Codes All calls made to the Campbell’s Kitchen API returns a status code signifying the outcome of the request. These codes are processed within your application. If an API Error occurs, the JSON response will be <‘error’ : ‘message’> with the associated HTTP status code. The API will also return a message with more detail. Response Codes: Reasons: HTTP 200 OK Successful request made. No errors. HTTP 400 Bad Request Invalid API request i.e. a required parameter was missing or contained an invalid parameter value. HTTP 401 UNAUTHORIZED Missing API token, invalid API token, or request limit exceeded. HTTP 403 Forbidden API key invalid or missing HTTP 404 Not Found The API endpoint does not exist HTTP 500 Internal Server Error An unexpected error condition occurred. Please contact us if you see this error status message. Provide the conditions under which this error occurred, and what you were doing at the time. HTTP 503 Service Unavailable The API service is down for temporary maintenance. Try again in a while. Common Campbellskitchen.com urls http://api.campbellskitchen.com/recipes/search?category=1 http://api.campbellskitchen.com/recipes/search?ingredient=Beef http://api.campbellskitchen.com/recipes/search?ingredient=Beef|Broccoli http://api.campbellskitchen.com/recipes/search?name=Simple http://api.campbellskitchen.com/recipes/recipe/1234567