Consuming APIs in the front-end using module_data

Updated on 20-October-2016 at 10:16 AM

Business Catalyst End of life announcement - find out more details.

The background

Traditionally in BC modules are used to represent data from different components of the system. The e-Commerce section has its own set of modules used to display products, catalogs, different components like the shopping cart summary and so on.

With the introduction of BC Apps came a new generation of REST API endpoints . However, these endpoints can only be accessed using a BC app, from within the Admin Console.

The next step in this evolution would be a way of using the API endpoints in the front-end for unauthenticated users (site visitors) outside the limitations of a BC app. We have developed a new module that allows you to use the same API endpoints and display the data on the front-end (for site visitors) without creating a BC app.

Introducing {module_data}

This module is the missing link between front-end and REST API endpoints . It does not belong to any particular section, it can be used fetch any piece of data which can be accessed by the v3 API endpoints.

At the moment the v3 API endpoints which can be consumed using {module_data} are:

{module_data} is only used to render data that can be accessed by v3 APIs from the front-end. Do note only list-type of operations are supported. Create, modify or delete operations (the equivalent of POST, PUT and DELETE) are not supported.

Syntax

{module_data version="v3" collection="MyCustomers" resource="customers" fields="id,name" where="CONDITION" skip="0" limit="55" order="firstName" resourceId=""}

Note: With the flexibility module_data offers when accessing the server data its syntax can get pretty complicated. To make module_data easier to work with we have introduced the BC API Discovery app . This is a free tool that enables you to visually create complex queries you can then copy-paste right in your site.

This module has the following parameters:

Parameter name Mandatory Default value Meaning
resource

  This parameter is used to specify the name of the resource which is going to be queried.
version   This parameter is used to specify the version of the resource which is going to be queried. The value should be "v3"
collection   The name of the Liquid collection the result will be placed in.
skip   0 This parameter specifies how many records to be skipped (the offset from the beginning of the collection).
limit   10 This parameter specifies how many items to be included from the total number of items returned by the module.
where     This parameter is used to add a filter to the module.
order     This parameter specifies the ordering criteria.
fields     This parameter is used to add additional fields (which might be hidden by default).
resourceId     This parameter indicates that a specific item id must be fetched from the specified resource collection.
subresource     This parameter specifies the projection which must be queried for a given resource item.
Liquid specific      
template   empty This parameter specifies if the module output layout (html) is get from current page (inline) or from a custom template (template="" vs. template="[custom_templatefile_path]")

The Resource parameter

This parameter is used to identify the resource you want to query. If you look at its corresponding API endpoint URL, the resource parameter becomes self explanatory.

For example, to get the list of customers for a site you would call the "customers" endpoint : /webresources/api/v3/sites/current/customers, this is how the GET call looks like:

var request = $.ajax({
url: "/webresources/api/v3/sites/current/customers",
type: "GET",
connection: "keep-alive",
contentType: "application/json",
headers: {
"Authorization": $.cookie('access_token')

}

To get the list of customers in the front-end using module_data you will need to specify the "resource" field like so:

{module_data version="v3" collection="MyCustomers" resource="customers"}

and then display the MyCustomers collection using Liquid:

{{MyCustomers | json}}

What if we want to get the orders over $15? In this case we would use the orders endpoint and make a GET call to the /webresources/api/v3/sites/current/orders URL like this:

var request = $.ajax({
url: "/webresources/api/v3/sites/current/orders?where={'totalPrice':{'$gte': 15 }}",
type: "GET",
connection: "keep-alive",
contentType: "application/json",
headers: {
"Authorization": $.cookie('access_token')
}
});

Using the {module_data} we will need to get the "orders" resource and set the filter like this:

{module_data resource="orders" version="v3" where="\{'totalPrice':\{'$gte': 15 \}\}" collection="largeOrders"}
<pre>
{{largeOrders | json}}
</pre>

Note: When using filters always make sure you escape the curly and square brackets using a slash character.

The subresource parameter

This parameter is used to create more granular collections of data. Let's take a look at an example:

Using the secure zones endpoint we can list all the secure zones created on my site. The URL of the API endpoint we would use is /webresources/api/v3/sites/current/securezones and the syntax of the module_data looks like this:

{module_data resource="securezones" version="v3" collection="secureZoneList"}
{{secureZoneList | json}}

Now let's get the customers that are subscribed to the secure zone with the ID 51. The API endpoint URL would look like /webresources/api/v3/sites/current/securezones/51/customers and the equivalent module_data syntax:

{module_data resource="securezones" resourceId="51" subresource="customers" version="v3" collection="secureZoneList"}

Note: subresource is always used together with the resourceId parameter

Pagination, sorting and filtering

Just like their corresponding API endpoints the resources and subresources available to module_data can be paginated using skip and limit, ordered using order and filtered using where. For more detailed examples on using these methods take a look at the module_data sorting, filtering and partial representation methods article.

The main difference you need to remember is curly and square braces need to be escaped using a slash character.

Warning: By default all the items will be fetched, including the disabled ones. You would need to filter specifically only for the items enabled by using the where parameter (e.g. where="\{'enabled':true\}".