API Documentation

Introduction

The Interchange Design API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Authentication

Authenticate your account when using the API by including your username and secret API key in the request. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth password value.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Endpoint Paths

Interchange Design’s API endpoints are hosted from the base URL https://interchangedesign.com/api/. For example, the validate Location Code endpoint’s full path is:

https://interchangedesign.com/api/validate/{locationCode}

All endpoint paths include a locationCode parameter that indicates which of a business’s locations you would like to display information for.

Request Header

All requests should include the following header:

  • Accept: application/json

Handling Errors

All Interchange Design API endpoints include an errors array in their response body if any errors occurred during a request. The response body has the following structure:

{
  "errors": [
    {
      "category": "CATEGORY",
      "code": "12345",
      "detail": "Error Message"
    }
  ]
}

Error Categories

Indicates which high-level category of error has occurred during a request to the API.

Name Description HTTP Status Code
API_ERROR An error occurred with the API itself. 500 Internal Server Error
AUTHENTICATION_ERROR An authentication error occurred. 401 Unauthorized
INVALID_REQUEST_ERROR The request was invalid. Most commonly, a required parameter was missing, or a provided parameter had an invalid value. 400 Bad Request
NO_DATA No results were returned as a result of your API request. 404 Not Found

Error Codes

Indicates specific errors that can occur during a request to the API.

Code HTTP Status Code
INVALID_LOCATION_CODE 400 Bad Request
INVALID_PARAMETER 400 Bad Request
LOCATION_CODE_EXPIRED 402 Payment Required
NO_BEER 404 Not Found
NO_DATA 404 Not Found
NO_ITEMS 404 Not Found
QUERY_ERROR 500 Internal Server Error
UNAUTHORIZED_USER 401 Unauthorized

Validate

Validate Location Code

GET /validate/{location_code}

Path Parameters

location_code — string: A six character code representing your location

Returns

Name Type Description
location_code String Return the location code. This should match the location_code that was submitted.
active_tap_menu Boolean A boolean TRUE/FALSE value indicating whether or not a Tap Menu is live for the location
active_item_menu Boolean A boolean TRUE/FALSE value indicating whether or not a Item Menu is live for the location

Beer Menu

Beer Menu Object

An array of beer menu items

Beer Menu Item Object

Name Type Description
id String ID of the beer. Unique value.
menuPosition Integer Position of item on the menu board.
brewery String Name of the brewery associated with the beer.
name String Name of the beer
style String Style of the beer
ABV Float Decimal of Alcohol By Volume percentage
IBU Integer International Bittering Units value
description String Description of the beer
servings Array Beer Servings Object

Beer Servings Object

An array of servings for a beer menu item.

Name Type Description
servingSize Integer Number of ounces in the serving
servingMethod String How the beer is being served
amount String Amount, formatted in local currency, that the serving can be purchased for

Beer Menu Footer Object

Name Type Description
text String Beer menu footer text

List Beer Menu

Get all the beer that is on the menu for a specific location.

GET /beer/{location_code}

A sample response is as follows:

{
    "location_code": "U48WPK",
    "active_tap_menu": true,
    "active_item_menu": true,
    "beer_menu": [
    {
            "id": "8e79884e-2a5c-f8e6-fcf9-7c3ba6202d6a",
            "menuPosition": 1,
            "brewery": "Ballast Point",
            "name": "California Kölsch",
            "style": "German-Style Pale Ale",
            "abv": 5.2,
            "ibu": 23,
            "description": "The beer that launched Ballast Point.\r\n\r\nOur California Kölsch is a rich golden brew, crafted with aromatic German hops and rounded out with a blend of American and Munich malts. While it’s hopped like a lager, we ferment it like an ale to create a smooth, bright taste that has just a hint of fruit and spice. It’s extremely drinkable, like a Kölsch should be, yet complex, like a good craft beer demands.",
            "servings": [
                {
                    "servingSize": 4,
                    "servingMethod": "draft",
                    "amount": "$2.00"
                },
                {
                    "servingSize": 16,
                    "servingMethod": "draft",
                    "amount": "$6.00"
                }
            ]
        }
    ]
}

Path Parameters

location_code — string: A six character code representing your location

Returns

Name Type Description
location_code String Return the location code. This should match the location_code that was submitted.
active_tap_menu Boolean A boolean TRUE/FALSE value indicating whether or not a Tap Menu is live for the location
active_item_menu Boolean A boolean TRUE/FALSE value indicating whether or not a Item Menu is live for the location
beer_menu Array Beer Menu Object
beer_menu_footer Array Beer Menu Footer Object

Item Menu

Item Menu Object

An array of menu sections.

Item Menu Section Object

Name Type Description
id String Unique identifier for the menu section
menu_position Integer The position of the section relative to other sections
title String Section title
description String Section description
items Array An array of item objects

Item Object

Name Type Description
id String Unique identifier for the menu item
name String Name of the menu item
description String Description for the menu item
variants Array An array of variant objects
modifiers Array An array of modifier objects

Variant Object

Name Type Description
id String Unique identifier for the item variant
menu_position Integer The position of the item relative to other items in the same section
sku String SKU for the item
variation String Descriptor/name for the variation (e.g. Regular)
amount String Amount, formatted in local currency, that the variant can be purchased for

Modifier Object

A collection of modifier sets

Name Type Description
id String Unique identifier for the modifier set
name String Name of the modifier set
menu_position Integer The position of the modifier set relative to other modifier sets for the same item
options Array An array of modifier option objects

Modifier Options Object

Modifier options that can be applied to a menu item. Only modifier options that have a boolean value of true for the “Display on Menu” attribute will appear in the API response.

Name Type Description
id String Unique identifier for the modifier option
name String Name of the modifier option
amount String Amount, formatted in local currency, that the variant can be purchased for
menu_position Integer The position of the modifier option relative to other modifier options in the same set

List Item Menu

Get all the items on the menu for a specific location.

GET https://interchangedesign.com/api/items/{location_code}

A sample response is as follows:

{
    "location_code": "KHEEPH",
    "active_tap_menu": false,
    "active_item_menu": true,
    "item_menu": [
        {
            "id": "4e74f6cc-f8db-c042-aefb-01d8cddfd7ee",
            "menu_position": 1,
            "title": "Burgers & Fries",
            "description": "Because they're delicious...",
            "items": [
                {
                    "id": "72331258-f959-b63f-df9d-ef8bbaec342f",
                    "name": "Hamburger",
                    "description": "Toasted buns, beef patty, onions, lettuce, spread, tomato",
                    "variants": [
                        {
                            "id": "60fa934a-2ec5-09e5-2223-b915029fc0b7",
                            "menu_position": 1,
                            "sku": "",
                            "variation": "Regular",
                            "amount": "$2.30"
                        }
                    ],
                    "modifiers": [
                        {
                            "id": "e60fe9bd-66f1-a25d-0209-85f14a11f53b",
                            "name": "Animal Style",
                            "menu_position": 1,
                            "options": [
                                {
                                    "id": "2e5b43b8-8f86-32e3-8560-30a3691c4f61",
                                    "name": "extra spread",
                                    "amount": "$0.00",
                                    "menu_position": 1
                                },
                                {
                                    "id": "53adae32-1ae9-2b97-fdfc-2d2d1c0af35c",
                                    "name": "add pickle",
                                    "amount": "$0.00",
                                    "menu_position": 2
                                }
                            ]
                        },
                        {
                            "id": "a42286ef-52c9-8d75-9d89-19ef7cb758eb",
                            "name": "Protein Style",
                            "menu_position": 2,
                            "options": [
                                {
                                    "id": "60bec801-598d-8c86-9e89-decd49fb7c5a",
                                    "name": "Your favorite burger wrapped in hand-leafed lettuce instead of a bun",
                                    "amount": "$0.00",
                                    "menu_position": 1
                                }
                            ]
                        },
                        {
                            "id": "87b6df32-765b-f36a-2339-3defa55f20de",
                            "name": "Onions",
                            "menu_position": 3,
                            "options": [
                                {
                                    "id": "12a0d0fc-9e90-4d6d-cbe0-8e5c31f584b6",
                                    "name": "Add Onions",
                                    "amount": "$0.25",
                                    "menu_position": 1
                                },
                                {
                                    "id": "89b36e71-cf48-658b-1f02-0a114eb9f9cb",
                                    "name": "Grilled Onions",
                                    "amount": "$0.00",
                                    "menu_position": 2
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Path Parameters

location_code — string: A six character code representing your location

Returns

Name Type Description
location_code String Return the location code. This should match the location_code that was submitted.
active_tap_menu Boolean A boolean TRUE/FALSE value indicating whether or not a Tap Menu is live for the location
active_item_menu Boolean A boolean TRUE/FALSE value indicating whether or not a Item Menu is live for the location
item_menu Array Item Menu Object

Published Date: July 22, 2017

©2018 Interchange Design

Twitter Instagram