Featured: InstantAPI

InstantAPI wins MODX Add-on of the Month, Dec 2012

Instant API

InstantAPI is the freshest MODX add-on on the block. Developed by Aaron Ladage, this Add-on allows you to add 100% JSON support to your website without having to code or even modify your templates! While this Add-on would have been a contender for being the first add-on to be featured under the new monthly MADX Award, which features the up-and-coming MODX Add-on of the month, it takes the gold more so for it's ultra-simple installation process than any specific functionality.


Getting Started

InstantAPI has a two step installation process:

Install InstantAPI:
  • Install the plugin via the MODX repository, and make sure the "OnPageNotFound" event is checked.
  • Visit any page on your site, and add ".json" to the end of the URL. The page will return a JSON-formatted string containing all of the page's data.

Once you install the Package you'll see a InstantAPI Plugin in your Elements Tab. Enable the Plugin, visit a resource of your webpage on the front end and add .json to the end of the URL and you should notice a JSON Object representing the assoicated resource is served.

See an example page.


Use Cases

One of the core features of MODX is that your resource tree often represents the structure of your site. This is great because translating a website from HTML to XML or JSON or anything else likely won't require any sort or restructoring of your content in MODX. Much like XML does not limit you to what nodes can have what attributes, or how many depths of child nodes there can be, MODX does not limit you to how many resources you can have or how they can be arranged. So naturally, you'll be building your website in a way that makes it easy to convert to a web application without even knowing it.

This is why InstantAPI for MODX is so great for those "well we built a website, now we need a web app" situations. You may find that all you need to do is install the add-on and start consuming JSON!

It's very easy to generate URLs to JSON feeds of your MODX Resources. 

<a href="[ [~5? &scheme=`full`] ]" data-json-url="[ [~5? &scheme=`full`] ].json">Products</a>

This creates an absolute link to your Products page (id 5) as well as an absolute URL to use to grab the data.

Wait up:
Need help getting JSON data? Then post a comment!


- With the Author -

• How long have you been using MODX and how did you hear about it?

I started using MODX Evolution almost four years ago (before it was even called "Evolution"), and transitioned to Revolution about a year and a half ago. Before learning MODX, I had been experimenting with a few other CMS options, including Joomla, Drupal, WordPress and Typo3, but after reading a Nettuts tutorial on MODX, the concept of a CMS that didn't impose its own limitations really clicked with me. I've never looked back.

• What's the first project you built with MODX?

Oh man...I don't think I can remember or want to admit my first project -- it was probably a mess! One of the first I'll claim, though, was a recoding of a school district's homepage. The entire site was built on a very restrictive vendor CMS that forced them to build the homepage in Flash (not a great idea for an organization that has to meet accessibility guidelines). I recoded the design outside of their CMS using standards-based HTML and added a news management system in MODX for managing and displaying online press releases on the homepage and elsewhere.

• When did you first come up with the idea for InstantAPI?

It was out of necessity, really. I was building sites that contained a lot of information that other people wanted to pull into their sites, but building a separate feed system was just too cumbersome in a lot of cases. After I built the first InstantAPI concept, it dawned on me that this wasn't just useful for creating feeds; it's also a dead-simple way to build out an AJAX-driven MODX site. Need to grab content from another page dynamically with JQuery? Just throw a ".json" extension on the page you want in your .getJSON call, and you're done.

• What do you think of the MODX Plugin system to hook into system events?

It's amazing! System events make the impossible possible, and InstantAPI is a perfect example of this. In this case, I needed a way to change a page's output from HTML to JSON on the fly. What I came up with is a plugin that only fires on the OnPageNotFound system event (aka, a 404 error), which is what happens when you tack on the ".json" extension in the URL. It just takes the URL, finds the corresponding page in the database and grabs all of its data with a simple getObject API call. That data is then formatted into JSON, output to the page, and the whole 404 process is killed. If it can't find that matching page, the 404 event continues, uninterrupted. This won't even interfere with pages that really do have a ".json" extension, since those pages do exist and won't trigger the 404 event in the first place. With about 25 lines of code and a single system event, I was able to completely change MODX's behavior, without hacking the core or affecting normal page load operations. That's downright magical.

• What led you to release it as an add-on?

I have tons of add-on code laying around that is useful to me, but probably not to a lot of other people. In the case of InstantAPI, I realized that I was using it over and over again, and that it might have a place in the larger community. 

• Is there a roadmap of any feature you'd like to add on the future?

There's one feature that is sorely needed as soon as possible, and that's template variable support. Coding it isn't too complex, but I'm still trying to plot out the best way for developers to manage this without making its implementation any more complex than a single plugin (aka, I don't want to involve chunk or template dependencies, as I feel that would detract from the simplicity of this solution). Look for that support in the next few weeks. I'd also eventually like to add support for Articles, since those pages behave a little differently from normal resources and may not be that useful with InstantAPI as it currently works.

• What sorts of things have you used JSON to accomplish?

I work full-time for the University of Kansas, which is now a Drupal campus. Several of the applications I've built are better suited for a framework-like CMS such as MODX, but that usually means I also have to find some way to syndicate my application data back to the Drupal mothership. Because of that, a lot of the MODX sites I've built don't even have an HTML front-end -- I'm basically just using it as a giant JSON-generating API engine!

• Do you have any other MODX Add-ons in the works?

If I can find the time, I have several! I developed a plugin that helps keep "internal" links fresh across duplicated contexts -- in other words, it prevents you from having to go through every page on your duplicated context and fix all the links to point at the new context instead of the old one. It works great but is very specific to the site it was built for, so I'm trying to figure out a way to make it general-purpose enough for everyone to understand and use. I'm also going to be building an events registration system for a freelance client, which I might release, depending on how it turns out. Other than that, I'm going to start taking a look at some of my previous add-ons (ContentVampire and PageLocker, especially) and try to make them more full-featured and easier to use.

Comments (6)

  1. Aaron Ladage:
    Dec 06, 2012 at 12:17 PM

    Thanks for the award and the nice write-up, JP! I think these awards are a great way to shine a light on the platform and its developers (and I'm not just saying that because I won, haha). Keep up the good work!

  2. YJ Tso:
    Dec 07, 2012 at 10:03 AM

    Awesome Post JP!!!

    And congrats on the award Aaron :) You deserve it - fantastic work!

  3. Saritha T S:
    Apr 11, 2013 at 01:34 AM


    I want to get the MODX page contents in json format to use for mobile applications. I have installed InstantAPI and enabled in our test environment. The web pages I am seeing as .html pages. I have added .json at the end of the url, but the page is showing the home page and in html format. Could you please help me on that how we get the .json data.

    Thanks in advance,

  4. JP DeVries:
    Apr 11, 2013 at 02:09 AM

    That sounds strange, InstantAPI should definitely work if it's the exact URL + .json (did you try with or without a slash at the end). One thing I'd recommend is finding the InstantAPI Plugin in your Elements Tree and make sure it is enabled. If it still isn't working something must be up and we might have to help you add some debugging statements to see what's going on.

    Unless Aaron has any other bright ideas of course :)

  5. Saritha T S:
    Apr 11, 2013 at 04:03 AM

    Yes, InstantAPI is enabled and I have tried with or without slash at the end. My URL is like http://localhost/modx/2.html.json. Is there anything to be enabled? I am a starter in MODX and I have no much idea in it.

  6. Aaron Ladage:
    Apr 11, 2013 at 10:25 AM

    Hi Saritha,

    Thanks for getting in touch. I'm noticing two issues: first, you sent a link to localhost, which is running on your local computer, so JP and I won't be able to test with you. However, I think the bigger issue is that you still have ".html" in the URL you're trying to use. Instead, try http://localhost/modx/2.json, and see if that works.

Add a Comment

Allowed tags: <b><i><br>Comment:

** Instant JSON API for your Resources **