In my previous Mura Demystified post, I delved into the mysterious waters of the JSON API, a powerful tool for integrating JavaScript-based applications into Mura.

The API solves a lot of problems that I'm sure any content developer, manager or reader has encountered. For instance, "How do I best deliver this piece of content, targeted to X platform(s), knowing that how/where/when it is used could change depending upon the who/what/where…"

You see where I'm going with this? Murky waters indeed.

Keep it Simple

The magic is in finding ways not to have to worry about any of that. Mura's JSON API is the start, along with the content feeds it delivers. Up close it is a simple, flexible tool for delivering standardized, self-describing blocks of content. Move the lens further back and you discover a wealth of functionality: filtering, sorting, pagination, permissions, and more.

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, let's take a look at how we can interact with this data, adding filtering and sorting.

I Before E

Sorting can be applied to a JSON API request using terminology familiar to Mura 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 five. 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

Less is More

Filtering should also look familiar if you've worked with Mura before.

http://mura.test/index.cfm/_api/json/v1/getmura2/users/?lname=johnson

params ": {

   "lname": "johnson",

   "entityname": "users"
   }

This will match any user with the last name of "Johnson".

Multiple filters can be added to each request, and conditional criteria can be passed in using the ^ delimiter, e.g.:

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 feed of "Users" containing any records with a last name value of  "johnson" and a first name containing the letters "ma". For a full list of the filter criteria available, refer to the v6 and/or  v7 Mura Feed documentation.

Examples, Please

If you want to have some fun playing around and testing JSON API feeds on your Mura website, I suggest trying Steve Withington's "JSON API Tests".  Follow the simple directions in the comments at the top of the page, to create a simple API testing page within your own Mura site.

Mura's JSON API can also be explored using an API development utility like Postman or Swagger's API inspector to communicate the endpoints defined within the API output itself.

The JSON API was a crucial component in the push towards enabling a completely "headless" experience, with Mura CMS running strictly as a Content-as-a-Service (Caas) application. As of Mura 7.1, every bit of content is available for remote consumption, complete with Mura's robust security and integrated permissions.

Up Next: Mura JS

In the next Mura Demystified post we're going to move on from the JSON API to exploring Mura JS, a swiss army knife of JavaScript goodness that will push you into a place of coding nirvana. I'll start by examining 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.

Also See:

JSON API Endpoint Reference: docs.getmura.com/v6/back-end/json-api

JSON API Test [gist]: gist.github.com/stevewithington/c83247c89c9924a5d66e

Mura Feed Docs: docs.getmura.com/v7/mura-developers/mura-beans-objects/common-bean-objects/feed-bean/

Related Blog Posts:
getmura.com/blog/mura-demystified-the-json-api-your-next-favorite-thing/ 
getmura.com/blog/introducing-the-immutable-mura-7-1/