In my last blog post I delved into the mysterious waters of the JSON API, a powerful tool for integrating JavaScript-based applications into Mura CMS. I've only covered the basics so far, so this time I'm going to dive a little deeper and look at one of the most common tools developers use when working with Mura CMS: Feeds.

What is a Mura Feed?

For the uninitiated, a Mura Feed is essentially a collection of content that contains all of the information and tools necessary to browse, sort and filter itself.

Let's take a look at a basic Mura JSON API request:

http://mura.test/index.cfm/_api/json/v1/getmura2/content

What this produces by default is essentially a feed sans any filters or criteria. The results might look something like this:

{
    "data": {
        "endindex": 20,
        "startindex": 1,
        "entityname": "content",
        "totalpages": 11,
        "totalitems": 210,
        "links": {
            "entities": "http://mura.test/index.cfm/_api/json/v1/default",
            "self": "http://mura.test/index.cfm/_api/json/v1/getmura2/?&entityname=content&siteid=default&method=findall&pageIndex=0",
            "properties": "http://mura.test/index.cfm/_api/json/v1/getmura2/content/properties"
        },
        "itemsperpage": 20,
        "items": [],
        "pageindex": 1
    },
    "params": {
        "entityname": "content",
        "siteid": "default"
    },
    "method": "findAll",
    "apiversion": "v1"
}

In this example, you can see there is a fair amount of meta information relating to the request. We have the params section which includes all the criteria that forms the request, at its most basic including the siteid and the entityname that we are working with. There are also a number of important values present in the data (the response portion of our request) area.

startindex: this is the start position for the results that have been returned. If you were looking at records 21-40, this value would be 21.

endindex: the last index position of the data returned. If you were looking at records 21-40, this value would be 40.

itemsperpage: this is the number of items that will be returned within each "page" of content.

totalitems: this is the total number of items based upon the current criteria, i.e. the "record count"

totalpages: this is the total number of pages that are available based upon the current criteria. If itemsperpage = 20 and the totalitems = 200, this number would be 200 / 20 = 5.

items: this is the array of items returned based upon the current criteria. There will be no more than "itemspserpage" items within this array.

pageindex: the current page being viewed 

Now, lets take a look at how we can interact with this data, adding filtering and sorting.

Sorting

Sorting can be applied to a JSON API request using terminology familiar to Mura CMS developers. These essentially work like "query params" in the feed request.

http://mura.test/index.cfm/_api/json/v1/getmura2/content/?itemsPerPage=5&sort=title

When we run this request, we will see a few changes in the parameters section:

params ": {
    "pageindex": 1,
    "itemsperpage": 5,
    "sort": "title",
    "siteid": "default",
    "entityname": "content"

This will sort the response by the last name, and limit the number of returned items to 5. If we want to do a reverse (descending) sort, we add a minus sign to the sort criteria like this:

http://mura.test/index.cfm/_api/json/v1/getmura2/content/?itemsPerPage=5&sort=-title

Filtering

Filtering should also look familiar to you if you've worked with Mura CMS before. We can add multiple filters to each request like so:

http://mura.test/index.cfm/_api/json/v1/getmura2/users/?lname=eq^johnson&fname=containsValue^ma

In this case, the params request will look like this:

params ": {
    "pageindex": 1,
    "itemsperpage": 20,
    "fname": "containsValue^ma",
    "lname": "eq^johnson", 
    "siteid": "default",
    "entityname": "users"

This will return a users feed that matches anybody with the last name of "johnson" and contains the letters "ma". For a full list of the filter criteria available, you can refer to the v6 v7 Mura Feed documentation.

If you want to have some fun playing around and testing JSON API feeds on your Mura CMS website, I suggest trying Steve Withington's "JSON API Tests" app that he wrote. Simply copy the file into your instance of Mura CMS and have fun!

In the next blog post we're going to migrate from the JSON API to Mura JS, the Mura CMS JavaScript library that packages the JSON API functionality plus a whole lot more.  I'll take a look at some of the remote functionality it offers, and then we'll deep dive into a couple of practical examples that showcase how powerful and flexible this technology can be.