Show data from an API

In this tutorial you connect a REST API, write a query that fetches a list of posts, and show each post as a card on the page. The example uses JSONPlaceholder, a free test API that needs no key, so you can follow along with nothing but a site.

Connect the API

1. Open the Data workspace

   Open the page you want to work on, then press Data at the bottom of the left sidebar. The Data workspace lists the page's variables, queries, formulas and the site's integrations. Press Data again, or its close icon, to go back to the canvas.

2. Add a REST integration

   Next to Integrations, press + (Add integration) and choose REST API. Name it Placeholder API.

   In the Connection card, set Base url to https://jsonplaceholder.typicode.com. Leave Auth type on none: this API is public.

3. Create it and test the connection

   Press Create integration. A Test connection card appears: press Run test and wait for Connected. The test uses the saved settings, so save again before you test a change.

Write the query

1. Add a query

   Next to Queries, press + (Add query). Rename the query from query to posts in the field at the top. Its result is now available as queries.posts.data.

2. Point it at the API

   In the Source card, set Integration to Placeholder API. The Operation switches to Request.

3. Fill in the request

   In the Input card, keep Method on GET and set Path to /posts?_limit=6. The path is added to the base URL, so the query asks for the first six posts.

4. Choose when it runs

   In When it runs, pick Static. The query runs when you publish and the posts are written into the HTML, which is fast and good for search engines. Pick Server when the data must be fresh on every request, or Client when it depends on what the visitor does in the browser.

5. Test it

   In the Result card, press Run. The response appears as a tree: an array of six objects with userId, id, title and body.

Show the posts on the page

1. Insert a collection list

   Go back to the canvas and select the page frame or a section. Press + in the Layers tab and choose Collection list. It is a three-column grid with one child, Item, that repeats once per post.

2. Use the query as its source

   With the list selected, open Collection list in the inspector. Set Source to Expression if it is not already. Items is filled in with queries.posts.data; if not, press its bind button and type it.

3. Add text to the item

   Press T and drag inside Item to add a text for the title, then add a second text for the body. Every repeat of the item gets the same layers.

4. Bind the texts

   Select the title text. In Typography, press the bind button next to the text and type item.title. Bind the second text to item.body the same way. Each card now shows its own post.

5. Style one card

   Select Item and give it padding, a fill and a border radius. The style applies to every card, because they are all repeats of the same item.

Handle an empty result

1. Write the empty state

   Select the collection list and set Empty text to No posts yet. This text shows instead of the cards when the list has no items.

2. Try it

   In the Data workspace, change the query's Path to /posts?userId=999. No user has that id, so the API returns an empty array and the canvas shows your empty text. Set the path back to /posts?_limit=6 when you are done.

3. Preview and publish

   Press ⌘↵ to preview the page, then press Publish. A static query runs during the publish, so the published page has the posts in its HTML.

What you learned

• An integration holds the base URL, headers and secrets; queries reuse it.
• A query picks an operation, fills its input and runs as static, server or client.
• A collection list with an Expression source repeats its item for each element of a query result, and item.* reads the current element.

Read the guides behind this tutorial: