About the Beef API v2.0

General Information

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.

Support:

For technical questions regarding our endpoints and data, please email us.

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:

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:

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

August 5, 2020:

July 18, 2019:

May 23, 2019:

March 12, 2019:

February 25, 2019:

January 23, 2019:

November 9, 2018:

April 30, 2018:

October 12, 2017: