Understanding the amp-list component

TL;DR: <amp-list> requires served JSON from an https endpoint for production because it wants your page to work anywhere, but allows you to use a local testing environment if serving from a webserver on localhost

The <amp-list> component is a great way to add a dynamic aspect to AMP pages. It is one of the components of AMP that can bring in outside data and render it on load, both when the AMP page is accessed directly and from the AMP Cache. With this ability come a few restrictions.

A common gripe developers encounter when first trying out amp-list is the inability to access JSON that is stored locally on the file system. You can’t simply point the source towards a file sitting next to your AMP page and render it in your browser.

The reason this is enforced is fairly simple: you don’t know how someone is going to visit your page. If the user comes to your page through a direct link, then you could download some JSON from your webserver and do as you please. But with AMP, that isn’t always the case. If the user accesses your page from Google Search in the AMP Viewer, then you have a problem. The data won’t be stored on the cache. You need to be able to download the dynamic information from any context. Hence, you need an endpoint (or some way for the cache to infer an endpoint).

The specific error in this scenario is as follows:

"source" "must start with "https://" or "//" or be relative 
and served from either https or from localhost

Okay so what does that mean? That’s a lot of ‘or’s and ‘and’s.

You basically have 4 options:

  1. The source starts with “https://”: This is where you have an endpoint, and it’s secure, so you win. Great work, you must be very proud.

  2. The source starts with “//”: This means you can use a protocol relative URL. This isn’t too common (it’s considered an anti-pattern), since you want to ensure that you are accessing resources with HTTPS. For those who might not know, using a relative protocol accesses the resource using whatever protocol is being used to view the page. So if you visit via HTTP, it will make a request for the JSON object using HTTP. However, in practice, since you hope to have your page be accessible from the AMP cache, you want your endpoint to recieve HTTPS traffic. This basically devolves to being the same option as #1.

  3. The source is relative and is served from https: Probably the most common way to set it up. As long as your site is secured with HTTPS, you’ll be able to access content on the site using relative paths. What’s great about the AMP Cache is that it will rewrite relative URLs into absolute URLs, so you don’t have to worry about cached pages not being able to reference your sources.

  4. The source is relative and served from localhost: Obviously for testing. If you’re testing things locally this is the fastest way to get up and running (interestingly enough this doesn’t work with, but does with ‘localhost’ or simply a relative path)

That’s a lot more options than really matter for the original local testing scenario; I just think it’s interesting to examine all of the options. It also raises some interesting questions. If protocol relative URLs are an anti-pattern, why are they even an option? Why can’t you use Something to investigate for later, perhaps.

Generally, for local testing, this means that you need to boot up a server in the root directory where your AMP page lives. This makes it pretty easy. The method can vary, but in a Linux environment simply invoking php -S localhost:<port-number> should be more than sufficient.

Of course, that’s not all. We also have to deal with the AMP CORS specification, which we will investigate in my next post.

Phillip Kriegel

Super speedy sites