Getting Started with Business Catalyst's APIs

Business Catalyst offers a wide range of APIs which allow developers to easily extend the core functionality of the platform, create entirely new applications on top of our infrastructure, and integrate with external third-party systems.

Supported APIs

Business Catalyst currently supports two protocols: the older eCommerce and CRM APIs utilize the SOAP protocol, while all new APIs are RESTful over HTTPs.

Interacting with APIs

When making API calls you need to be in the context of a BC app. This means you will need to register an app key and create a simple app that will provide the context for your API calls.

Take a look at the Building a basic "Hello World" custom app section to get your app going as quickly as possible.

Before you get started

There are a few important things to watch out for when interacting with BC's APIs:

  • We recommend to access the API endpoints using relative paths. That is because API calls are using the domain of the app they run in, not the site's domain. Take a look at the Authorize your API calls article for more details on how this works
  • In the endpoint's request path we recommend to use current instead of the actual siteID
  • Once you've finished the authorization sequence and got the access token, always send this as an "Authorization" header with your HTTP request

Example API requests

Before running any API calls you will need to register a BC App key in your Partner Portal and install a "blank" app like sothe "Hello World" sample app.

Once the app is installed click its menu entry in the Admin console to open up the app and then hit F12 to open up Chrome Developer Tools.

Switch across to the "Sources" tab, open up the index.html landing page and add a break like so:

This break will pause the script and will allow us to run the test API calls while in context of the app.

After adding the break, click the app's Open Admin menu item again. This should fire it again and this time it will stop at the break we added.

At this point you can test any of the API calls available, let's take a look at a few of them.

1. Get a list of Web Apps that exist on the current site

Now that we are in the app's context, got the access token we can pass it through as an Authorization header to access the range APIs available.

Let's grab a list of the Web Apps that exist on the website we're currently logged in to. Paste the following code into the Console and hit enter to run:

// Perform the AJAX request (make sure you've set the access token)  
var request =
    $.ajax({
        url: "/api/v2/admin/sites/current/webapps",
        type: "GET",
        headers: {
            "Authorization": $.cookie('access_token')
        },
        contentType: "application/json"
    });
// Request successful, response is in "msg" variable  
request.done(function (msg) {
    console.log("Request successful");
    console.log(msg);
}); // Request failed, you can add your own error handling  
request.fail(function (jqXHR) {
    console.log("Request failed. Error code: " + jqXHR.status);
});

If the request is successful, you'll be returned a object containing the response data documented here.

Again we've used jQuery to send an AJAX request to the List Web Apps API endpoint and written some simple success/error handling to deal with the response. You'll notice we're able to use current in the place of specifiying the Site ID, as we're sending the request to our secure/system site URL.

From the returned object, you could then use the Get Web App Item List method (sending the ID of the desired Web App) to request a list of all items that exist for a specific Web App.

2. Create a new Web App

We can also easily create an actual Web App using the API. This time we'll be using a POST request instead of a GET request, as we need to tell BC what we want our Web App to look like.

// Perform the AJAX request (make sure you've set the access token)  
var request = $.ajax({
    url: "/api/v2/admin/sites/current/webapps",
    type: "POST",
    headers: {
        "Authorization": $.cookie('access_token')
    },
    contentType: "application/json",
    data: '{"name": "MyWebApp"}'
}); // Request successful, response is in "msg" variable  
request.done(function (msg) {
    console.log("Request successful");
    console.log(msg);
}); // Request failed, you can add your own error handling  
request.fail(function (jqXHR) {
    console.log("Request failed. Error code: " + jqXHR.status);
});

You'll notice that this time we've specified the type as POST and sent some JSON data through to BC that defines our new Web App's properties.

You can expand upon this JSON string to set a range of other Web App properties. See the parameters here for a complete list of what's supported.

3. Add a new Web App item

Now that we have an empty Web App, let's add an item. Paste the following code in the Console and hit enter to run:

Note: You'll need to replace MyWebApp with the name of your actual Web App for this to work.

// Perform the AJAX request (make sure you've set the access token)  
var request = $.ajax({
    url: "/api/v2/admin/sites/current/webapps/MyWebApp/items",
    type: "POST",
    headers: {
        "Authorization": $.cookie('access_token')
    },
    contentType: "application/json",
    data: '{ "name": "MyWebAppItem" }'
}); // Request successful, response is in "msg" variable  
request.done(function (msg) {
    console.log("Request successful");
    console.log(msg);
}); // Request failed, you can add your own error handling  
request.fail(function (jqXHR) {
    console.log("Request failed. Error code: " + jqXHR.status);
});

We're using the Create Web App Item API method and an AJAX POST request to send BC the details of our new Web App item.

Just like our previous example, we've defined the Web App Item name here using JSON data sent during the request. You can find a full list of item supported parameters here.

To update an existing Web App item, you use the PUT HTTP method instead of POST. See the Update webapp item reference article.