About the Beef API

General Information

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

API Endpoint:
The endpoint for the current API version is http://beefapi.beef.org/api/v1. All URLs mentioned below are relative to the endpoint. The endpoint address may change in future versions of the API. The Beef API can also be called over secure communications(HTTPS), and that endpoint is https://beefapi.beef.org/api/v1

Response Formats:
The data returned by the API can be encoded in JSON/JSONP or XML formats. You will need to simply set the ContentType in the header of your request to either:

(Content-Type: application/json)
(Content-Type: text/XML)

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%.

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 search API endpoint, there are acceptable search parameters that represent certain attributes to describe a recipe. Use the following helper call to identify the acceptable search parameter values that can be passed to the search endpoint. If you call the search API endpoint with a value that is not found in the search parameter collections, this value will be ignored.

https://beefapi.beef.org/api/v1/GetSearchParameters

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.

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/v1/recipes/search?qaw=&pageNumber=1&itemsPerPage=10",
      "title": "Search Recipes"
    }
  ]
} 

Response Codes

Here are some common HTTP response codes:

Endpoints

There are 7 endpoints available on the Beef API grouped into recipes(5) and collections(2). See the collections endpoint documentation and recipes endpoint documentation for more details.

Developer Requirements

Attribution and Acknowledgement

In accordance with “Guidelines For AMS Oversight Of Commodity Research And Promotion Programs,” issued June 2012, and the Beef Promotion and Research Act and Order, the Cattlemen’s Beef Board (CBB) requires proper acknowledgment of Beef Checkoff Program funding.

Logo purpose/intent

The beef check logo was designed for a single purpose: to identify programs funded by the national $1-per-head Beef Checkoff.

Why it’s critical to the industry

Because this logo connotes specific meaning wherever it appears, it is absolutely vital that everyone understands exactly when and how it is to be used.

Approved logo treatments

Below are the preferred treatments and should be used when possible. Please note that these logos have been carefully designed and should not be altered in any way. Always use approved artwork.

Guidelines for Beef API Branding

Your use of any Beef API content, whether served from your website or from a client application, must appropriately attribute the Beef Checkoff by adhering to the following guidelines:

All applications must feature either the language "Courtesy of BeefItsWhatsForDinner.com" or one of the Beef Checkoff logos found below on any page or screen that displays Beef API content or data.

The position of the Beef API attribution text or logo must be adjacent to where your app is using Beef Checkoff content in the UI.

The text or logo must link directly to http://beefitswhatsfordinner.com/.

Logos cannot be altered or resized.

Beef Checkoff Logos

Use only the Beef Checkoff logos provided below. Select the logo that best suits the visual design and functionality of your site or application.

Minimum Size

Maximum Size

Retina Display @2x

Improper Usage

The Beef Checkoff logo must be used at the full size that is provided, and should be clearly visible, and not altered, resized, or obstructed in any way.

Do not change colors	Do not create custom graphics	Do not stretch or distort	Do not change the font
Do not manipulate the logo	Do not overlap or minimize clear space	Do not rearrange layout	Do not change wording

Clear space

The graphic functions much like a stamp of approval. As such, it should be surrounded by enough clear space or “breathing room” to ensure readability. It’s acceptable for the graphic to slightly overlap other design elements (photos, backgrounds, etc.), but the degree of overlap should not render the graphic or affected content unreadable.

Minimum area of isolation around the Checkoff logo

X-height = 1/5 the height of logo

Sizes

The selected logo must be used at the full size that is provided, and should be clearly visible, and not altered, resized, or obstructed in any way.

The logo must not be distorted by enlarging or shrinking, or appear too small, which affects content readability, clarity retention, and/or registration in normal use.

The Beef Checkoff logo should not be the most prominent element or logo on the Web page, nor the only branding on the page.

Colors

The logos above show the approved color values for use in electronic communications. When possible, the beef check logo should be reproduced with the word “BEEF” in black and the check in bright red. If not, a black-and-white reproduction is acceptable in situations where color is infeasible for some reason. Though designed primarily for a “positive” image on a light or white background, the logo also may be reproduced as a “reverse” or “negative” image, with white on a dark background, if all elements are equally balanced.

Restrictions

Do not use the logo or text attribution in a way that would suggest that the Beef Checkoff promotes or endorses you or any third party or the causes, ideas, websites, products or services of you or any third party.

For applications that do not easily support logos or text or where Beef API data are used in alternative media formats, you must contact us for alternative branding instructions prior to releasing your application to the public.

Prior written consent from the Beef Checkoff is required to use Beef API data without attribution.

The Beef Checkoff logo should not be the most prominent element or logo on the Web page, nor the only branding on the page.

Collections

1 - Search

The search API endpoint is used to search for collections of recipes. It will return a list of collections based on the search parameters provided.

The base URI for the collections search is:

collections/search?qaw=SEARCHQUERY

Search API Semantics

Parameters

Example URI for the collection search:

collections/search?qaw=SEARCHQUERY&pageNumber=PAGENUMBER&itemsPerPage=ITEMSPERPAGE&AuthorizationAppID=AUTHORIZATIONAPPID&AuthorizationAppKey=AUTHORIZATIONAPPKEY

What it returns

Requests to the collections search API will return the following data.

searchResults object

The search results object is the base object returned by requests to the collections search API. It typically contains an array of collection summary results.

collection summary array information:

2 - GET Collection

The GET single collection API endpoint is used to retrieve information about a single collection.

The base URI for the collection search is:

GET /collections/{id}

GET Collection API Semantics

Parameters

What it Returns

Requests to the GET collection API will return the following data.

Collection summary information

Recipes

The Beef API recipe API accepts GET requests. There are 5 endpoints in the recipes section.

1 - GET Acceptable Search Parameters

The GET available acceptable search parameters API endpoint is used to retrieve a listing of available lookup parameters that can be used in the recipe search endpoint.

The base URI is

GET /recipes/search/parameters

Parameters

What it Returns

Requests to the GET acceptable search parameters API will return the data.

searchParameters object

The search parameters object is the base object returned by requests to the recipe search paramters API. It typically contains an array of available search parameter results.

Available search parameter information:

Using this type of availableRecipeSearchParameters object can be likened to populating a html <select> with the key value pairs found in the returned result. Then those values can be submitted to the search API with there respective key

2 - Search

The recipe search API endpoint is used to search the Beef API for recipes.

The base URI is

GET /recipes/search?qaw=SEARCHQUERY

This endpoint relies on arrays of strings as parameter values. These values can be found by calling the GET acceptable search parameters endpoint. A call to this endpoint returns a search parameters object. Each item in search parameters array found in the search parameters object is matched to the name of the search API parameter name. For example, the call to GET /recipes/search/parameters returns:

  {
  "searchParameters": [
    {
      "name": "beefCutName",
      "acceptedValues": [
        {
          "attributeKey": "7-bone-chuck-roast",
          "attributeValue": "7-Bone Chuck roast"
        },
        {
          "attributeKey": "back-ribs",
          "attributeValue": "Back ribs"
        },
        ...
        ]
    },
    {
      "name": "beefCutType",
      "acceptedValues": [
                {
                  "attributeKey": "ground-beef",
                  "attributeValue": "Ground Beef"
                },
                {
                  "attributeKey": "roasts",
                  "attributeValue": "Roasts"
                },
                {
                  "attributeKey": "steaks",
                  "attributeValue": "Steaks"
                },    
                ...
                ]
    },         
    ...
   ]
}   
  

Now if you were to call the search API endpoint and wanted to pass in a search parameter for a beefCutName. You would need to pass only the acceptedValues attributeKey as an array to that place in the search endpoint query string. For example:

GET /API/v1/recipes/search?qaw=SEARCHQUERY&beefCutName=7-bone-chuck-roast,back-ribs&pageNumber=PAGENUMBER&itemsPerPage=ITEMSPERPAGE&apiCollectionName=APICOLLECTIONNAME&AuthorizationAppID=AUTHORIZATIONAPPID&AuthorizationAppKey=AUTHORIZATIONAPPKEY

GET Recipe Search API Semantics

Parameters

The parameters for the recipe search API are query string values added to the URLs provided.

What it Returns

Requests to the recipe search API will return the following data.

3 - GET Single Recipe

The GET single recipe API endpoint is used to retrieve information about a single recipe.

The base URI for the recipe search is:

GET /recipes/{id}

GET recipe API Semantics

Parameters

What it Returns

Requests to the GET recipe API will return the following data.

4 - GET Summary List

The GET recipe summary list API endpoint is used to retrieve a summary list of recipes for the given ids

The base URI for the GET recipe summary list is:

GET /recipes/getSummaryList/{recipeIDList}

GET summary list API Semantics

Parameters

Example URI for the GET recipe summary list:

GET /API/v1/recipes/getSummaryList/{id}?recipeIDList=RECIPEIDLISTARRRAY&AuthorizationAppID=AUTHORIZATIONAPPID&AuthorizationAppKey=AUTHORIZATIONAPPKEY

What it Returns

Requests to the GET summary list API will return the following data.

recipeListing object

The recipe listing object is the base object returned by requests to the GET summary list API. It typically contains an array of recipe summary results.

recipe summary information:

5 - GET All Recipes

The GET all recipes API endpoint is used to retrieve an abbreviated list of all the recipes available for the API.

The base URI is:

GET /recipes/getall

GET all recipes API Semantics

Parameters

What it Returns

Requests to the GET all recipes API will return the following data.

recipeList object

The recipe list object is the base object returned by requests to the GET all recipes API. It typically contains an array of recipe listing results.

recipe listing information:

This call is used to generate a listing of links to the actual recipe.