About the Beef API v2.0 BETA

General Information

Notice: The API and this documentation are currently in beta mode. For the next couple of months, the data structure and documentation are subject to change at any time. Still on V1? View API V1 Documentation.

 

The Beef API is based on REST principles and communicates over https.

API Endpoint

The base url for the current API version is: https://beefapi.beef.org/api/v2. All URLs mentioned below are relative to the endpoint. The endpoint address may change in future versions of the API.

Response Formats:

The data returned by the API is encoded in JSON/JSONP format. You may optionally set the Accept key in the header of your request to:

(Accept: application/json)

The Beef API also supports JSONP (Content-Type: text/javascript) as an alternative encoding. JSONP or "JSON with padding" is a JSON extension wherein a prefix is specified as an input argument of the call itself. If you pass a URL parameter named callback to the end point, the returned value will be wrapped in a function call where the function name is the value of the callback parameter.

For example:

&callback=YourFunctionNameHere.

Compression:

The API supports compressing response data with GZIP compression. This can be selected through the use of the Accept-Encoding header. Simply add (Accept-Encoding:gzip) to compress the data being returned. GZIP compression can reduce response size by up to 90%.

Caching:

The BeefAPI supports caching with strong entity tags(ETag). Clients are encouraged to make use of caching to improve performance and minimize the amount of data retrieval. With proper usage of ETag and Last-Modified response headers, along with the If-None-Match request headers, the API will indicate that cached data is still valid by returning a status code of 304. For more information please visit https://en.wikipedia.org/wiki/HTTP_ETag.

Authentication

In order to access the Beef API, you will need to obtain an AuthorizationAppID and AuthorizationAppKey from our developer site. The AuthorizationAppID and AuthorizationAppKey is required on every request made against the API. You can pass these values in the headers:

AuthorizationAppID:{ID}
AuthorizationAppKey:{Key}

Or you can pass these values in the query string of each request

&AuthorizationAppID={ID}&AuthorizationAppKey={KEY}

If your id or key is invalid, you will receive a http 401 error, Unauthorized.

Helper API Calls

For the Recipe, BeefCut, and Collection search API endpoints, there are acceptable values used for the search parameters that represent specific values used to search for an item. Use the following helper call to identify the acceptable search parameter key-value pairs that can be passed to the search endpoints:

https://beefapi.beef.org/api/v2/common/lookups

The general data structure of each lookup object will have a *Name and a *NameSlug property. The search endpoint parameter searches accept the "NameSlug" properties and will be an exact match on those values. If you call the search API endpoint with a value that is not found in the common lookup models, unexpected results may be returned.

These same model values will also be returned as part of the larger objects when they are called. For example, when calling a the "Get Recipe" endpoint, part of that object returned will be an array of attributes. This data structure matches the common/lookups attributes model, but will only return the attributes by type that are marked specifically for that ingredient. The same consistency is also true with other properties and sub properties of recipe allergens, collections, recipeType etc.

Calling the API

When you are ready to make an API request, you will need to:

  1. Have a valid AuthorizationAppID and Key

  2. Know which resource you are going to call

  3. Know what format you want your response returned to you.

Upgrading from API v1

There are breaking changes between v1 and v2 of the API. The v1 and v2 API's should not be used interchangeably as the v2 API is an entirely different database. The v1 API will be in a sunset status and is planned for "end of life" in early 2018. If you have not used v1 previously, then you may skip this section. Some of the major improvements in BeefAPI v2 are:

Media - The BeefAPI now uses Widen, a Digital Asset Management platform to dynamically manage licensed media. This allows for consumers of the BeefAPI to programmatically control dimensions and sizing of the BeefAPI media in their applications. To accomplish this, the API now returns a set of properties that will be used to generate a URL to embed media in any size and format. See the Media section for more information.

Beef Cuts - The BeefAPI now includes rich beef cut information end points that clients can build custom applications around. The cut endpoints, coupled with collection and recipe endpoints now provide a full experience from butcher counter to recipe information.

Collections - The BeefAPI has expanded the collections to now include beefcut and recipe collections. These collections are compiled by our expert staff and shared to consumers of the BeefAPI so that they can easily utilize current groupings of recipes and beefcuts in their applications.

Richer Recipe Models - The BeefAPI has many updated and new properties of the recipe objects. This includes, more detailed recipe ingredient, nutritional, and media information. See the Get Recipe endpoint for more information.

Media

The BeefAPI now uses Widen, a Digital Asset Management platform to dynamically manage licensed media. This allows for consumers of the BeefAPI to programmatically control dimensions and sizing of the BeefAPI media in their applications. To accomplish this, the API now returns a set of properties that will be used to generate a URL to embed media in any size and format. Media is can be found on Recipe, Recipe Ingredient, Recipe Instruction, BeefCut, BeefCut Uses, and Collection Models. Media will always be returned as an array in the following object model:

  • media array
    A list of media objects containing information about assigned media
    • widenURL string
      This is the base part of the URL that is needed to build the embed link
    • widenUID string
      This is the customer userid part of the URL that is needed to build the embed link
    • externalID string
      This is the unique identifier of the media item
    • filename string
      This is the filename of the media item
    • title string
      This is the title of the media item
    • caption string
      This is the caption used for the media item
    • mediaGroup object
      Media will always be returned grouped and sorted. Use this grouping to help manage any groupings that may be suggested from the BeefAPI. Object values found in this array will be an exact match to what can be found in the master list of mediaGroups in the common endpoint (/api/v2/common/lookups)
      • mediaGroupName string
        Name of the media group
      • mediaGroupNameSlug string
        URL-friendly slugged name of the media group
      • objectType object
        The type object this media group pertains to. Object values found in this array will be an exact match to what can be found in the master list of objectTypes in the common endpoint (/api/v2/common/lookups)
        • objectTypeName string
          The name of the object type
        • objectTypeNameSlug string
          URL-friendly name of the object type
      • mediaType string
        The type of media returned
      • sortOrder int
        The suggested sort order to be used for this media item
      • links array
        A list HATEOAS for this media item that is a link to view the media in its original size.
        • rel string
          The rel attribute specifies the relationship between the current document and the linked document
        • href string
          URI of the beefapi call to get more information for this links' context
        • title string
          Title of the link

Every media item has an ExternalID that uniquely identifies it. This ExternalID is used to generate an embed code, which allows you to place an image or video from Widen on your site in any size and format you choose, in addition to other customizations. For images, you can place this embed code inside of an <img> tag to display the image on your website.

This is the basic format for an image embed URL:

https://embed.widencdn.net/img/beef/{ExternalID}/{Dimensions}px/{Filename}.{Format}?keep={Crop Parameters}

For example, let’s say we have an image with the external ID of “asdfexample”. To show an image in JPEG format, with a size of 640 by 360 pixels, cropped to the top left (northwest) corner of the asset, you would generate an image tag like this:

<img width="640" height="360" alt="Example Image" src=”https://embed.widencdn.net/img/beef/asdfexample/640x360px/ExampleImage.jpg?keep=nw” />

Please read the Widen documentation on this topic for a complete list of customization options.

Audio, videos, pdfs, and other types of media are not currently supported. This is planned for a future update of the API.

Some important tips:

  1. You may enter anything you want for the filename; the ExternalID is what actually identifies the image. If you want to keep the file’s original filename, then there is a “filename” parameter that comes along with every image listed in the API. The file extension determines what format the image will be delivered in (jpg, gif, or png)
  2. For the image dimensions, you may choose to specify the width only, and have it resized according to the aspect ratio (example: 640px). Or similarly, you can also specify just the height (example: x360px). See the Widen documentation linked above for a full explanation.

HATEOAS

HATEOAS, an abbreviation for Hypermedia as the Engine of Application State, is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. For more information about this topic, please see https://en.wikipedia.org/wiki/HATEOAS.

Many of the Beef API endpoints contain an object called links. This is the Beef API implementation of HATEOAS. It is an effort to provide easy navigation to relevant endpoints in relation to the current API call. Each link object contains the following information:

rel (string) the relation of the link to the caller
href(string)the URL to the relevant API endpoint
title(string)the title of this API link

Error Handling

When an error is encountered you will receive a HTTP response code. And you will also get details returned to you in the body of the response. A typical recipe not found error response will look like:

{
  "httpErrorCode": 404,
  "httpErrorCodeDescription": "NotFound",
  "message": "The recipe you requested could not be found.",
  "description": "The recipe must be findable in the available SearchRecipe endpoint results.",
  "links": [
  {
    "rel": "search",
    "href": "https://beefapi.beef.org/api/v2/recipes/search?qaw=&pageNumber=1&itemsPerPage=10",
    "title": "Search Recipes"
  }
  ]
}

Response Codes

The BeefAPI will always return one of the following HTTP response codes for each call to an endpoint:

STATUS CODE DESCRIPTION
200 (OK) Request was successful.
304 (Not Modified) If you are utilizing the caching capabilities if the BeefAPI, you will receive a 304 response code when a cached item has been requested. It is expected that the consumer will use the cached version of the API data.
400 (Bad Request) Invalid format for your request. Make sure you're passing in the correct parameters.
401 (Unauthorized) Not authorized to make this request. Check the API documentation to be sure that you have access to the API or portion of the API you're making a request to.
404 (Not Found) The requested resource could not be found. Check spelling and review feed docs.
500 (Internal Server Error) Server side error processing request. Please try again later.

Interactive Documentation

It's easy to explore the BeefAPI directly via web browser by visiting our interactive documentation website. Throughout the documentation of each endpoint on this site, there are links to this site so that developers can easily test the BeefAPI without having to build any additional infrastructure.

Changelog

April 30, 2018:

Added Endpoints
calorieDietBasisText Get Recipe
Get Beef Cut

October 12, 2017:

Added Endpoints
sortOrder Get Recipe Collection
Get Beef Cut Collection
  • servingSize
  • prepTime
  • maxPrepTimeMinutes
  • cookTime
  • maxCookTimeMinutes
Get Recipe
Get Recipes By List
Get Recipe Collection
Search Recipe
Get Beef Cut Recipes
Updated Endpoints
recipes Get Recipe Collection
ingredients Get Beef Cut Collection
  • totalRecipeTime
  • maxTotalRecipeTimeMinutes
Get Recipe
Get Recipes By List
Get Recipe Collection
Search Recipe
Get Beef Cut Recipes