Front-End Insights

Polymer: dealing with the REST API using iron-ajax


In the previous post I showed you how data binding in Polymer works. The second very important thing in every JavaScript framework/library is how it communicates with the backend. The communication is usually performed via REST API. Today I will show you the predefined component (available in the official Polymer Elements Catalogue) iron-ajax which is created especially for this purpose.

Dealing with the REST API

I think it would be best to show you how to deal with REST API using the iron-ajax component by using an example. Let’s imagine we have a component which gets data from the GitHub REST API when it’s ready. This is how the component would look like:

<link rel="import" href="">

<dom-module id="show-repositories">
        <template is="dom-repeat" items="[[repos]]">


            is: 'show-repositories',
            properties: {
                repos: {
                    type: Array
            ready: function () {
            handleResponse: function (data) {
                this.repos = data.detail.response;

As you may have noticed, we have several new things here. I will explain them all.

Firstly, at the begging of the file we have a link to the iron-ajax component. I used the one from the CDN. In your production projects you will probably use a component downloaded via Bower (as it’s quite old technology, it still uses Bower).

Let’s move on and take a look at the iron-ajax definition inside the main template of the component. It might be weird for you (it was for me) but even if we want to use a component which has no UI and is intended for use in the code, we still have to place it inside the template of the component.
As you can see, the component has several attributes available. In the example we have url where you place the url to the API endpoint. We have also a params attribute where we can pass the JSON with parameters of the request. Of course, depending on the API, you could also use the body attribute instead of params. The last attribute we see here is on-response. By using this attribute you can tell the iron-ajax component what method will handle the response (in this case). Apart from this one, we also have on-error and on-request attributes available.
The full list of all available attributes of the component can be found in its documentation.

If we are on the subject of the response handler, let’s take a look at the handleResponse function defined in the object passed as a parameter to the Polymer function. As you can see, it has a parameter called data in this case. It’s just a response event object which has a response from the REST API inside its details property. We just assign the response data to the component’s property repos.

Now, let’s look at the ready function. It’s a standard method of Polymer which is invoked when the component is rendered and everything is ready. Please note how we access the iron-ajax component here:


By using this.$ we can access all DOM nodes available inside the template of the component. Please be patient when you use it because it doesn’t contain nodes added dynamically. Every node in the this.$ object is accessible by the value passed to its id attribute.
When we have access to the iron-ajax component, we can invoke the request using the generateRequest method. I did it this way to show you how to do it programmatically. If we want to do it automatically when the component is ready, we can set the auto attribute of the iron-ajax component instead. This will have the same effect as in this example.

Ok, so if we’ve invoked the request to the REST API and handled it, we can show the results on the UI. To do so, I used the template component (called template repeater) inside another template component. Please see how this is explained in the official documentation of Polymer:

The template repeater is a specialized template that binds to an array. It creates one instance of the template’s contents for each item in the array. It adds two properties to the binding scope for each instance:

  • item: the array item used to create this instance
  • index: the index of item in the array (the index value changes if the array is sorted or filtered)

So, in our example, we used this type of template passing the value of repos to its items property. Then, inside the the node of the template repeater, we have access to the item variable which contains a single element of the repos array. That’s how we can access the value of the name property and show it to the user.


In this article I have shown you how to deal with REST API in the most typical way. I think there are more custom components available on the Internet but, as I am still learning Polymer, I don’t know them yet 😉 If you know a better way to communicate with REST API, feel free to share it in the comments!

P.S. A working example of the code shown in this blog post is available on GitHub.