Tutorial 8 - Building a Liquid API GET Endpoint Page powered by GraphQL queries

this article shows a different use case for the skills you've already learned using a get request to run a query introduction so far, we've written graphql queries which run on page load this is powerful, but wouldn't it be even more useful if you could fetch data after page load when a user interacts with a site e g changing page on a list without refreshing the page? using xhr (sometimes called ajax) requests, you can run graphql at any time this approach can take a little bit of time to set up, but can allow you to create much faster interactive experiences for your users and opens up a huge range of possible solutions you can build we cannot document every way in which you can build this kind of page, but we will show you the basics and let your imagination do the rest! if you need additional support on this topic beyond the scope of what is documented here, we recommend you speak to one of our experts or browse the resources we link to at the end of the article glossary an api (application program interface) is a form of communication between two services on the internet communication takes place between 2 or more endpoints an endpoint in its simplest form is a url which allows an api access to a server or application on siteglide, we provide you with api endpoints we've built with our public api , but now you've learned graphql, you also have the ability to build your own endpoints when you need them a method defines the role of the api + endpoint e g a get method is for "getting" or "fetching" data json (javascript object notation) is a common file format for exchanging data which is efficient and human readable we'll use it in some of our examples (it's also the default format in which graphql results are outputted on the page ) steps for building your first liquid endpoint page powered by graphql step 1) create a page to serve as an endpoint the first step is to create a page on the siteglide admin which will become your api endpoint the slug you choose will be the url via which you'll eventually access the data it's worth naming the page and writing a slug which reflect the fact that this page is not a public facing page and should not be editable by clients e g /api/webapp 1 step 2) use cli to apply advanced settings to the liquid page in this step, we'll be changing the settings of the page in cli, as there are available settings here that are not yet editable from admin you can learn more about pages in platformos here https //documentation platformos com/developer guide/pages/pages#content and more about the siteglide cli here using the siteglide cli, pull down your site's files to your machine and open them up in a code editor of your choice set up siteglide cli sync so that changes you make will be pushed to the site open up the page you've created in a code editor of your choice we'll be editing the yaml configuration at the top of the page in my example, you can see the yaml settings between the triple dashes it's important when configuring yaml to use exactly 2 spaces instead of tabs for indenting your siteglide cli sync command will alert you to any validation errors \ layout templates/blank page max deep level 2 metadata name api webapp 1 get endpoint enabled true file type page last edit 1597241196376 redirect to '' redirect url '' \ 2\) a) method so far we've only learned to write graphql queries, so your endpoint will be handling get requests set the method property of your page to get method get 2\) b) format optionally, you can choose to change the format of your page if you like, instead of html, you can make your page a different format, like json format json note that if you set your page to a different format now, you'll need to append the url with the extension later e g a page with the slug my slug and format json can be accessed at the url /my slug json 2\) c) remove the page template as your endpoint page will not be accessed by either humans or search engine bots, it's much better to remove the page template, allowing you to only return the data you need layout "" 2 d) remove html unless you're using the html format from 2) b), you will need to remove any \&nbsp; tags automatically added to the page 2\) e) remove from search engine results unlike the other steps, this is not a yaml property on the page however, it's included here as a quick sensible step you can take you may wish to specify in your robots txt file that pages with this url should be ignored by search engines 2\) f) check yaml my example looks like this \ layout "" max deep level 2 metadata name api webapp 1 get endpoint enabled true file type page last edit 1597241196376 redirect to '' redirect url '' method get format json \ step 3) add a graphql query with variables add a query of your choice using the liquid graphql tag from tutorial 5 and variables from tutorial 6 in this example, i'll use the following query to fetch data from webapp 1 and change page with the page variable query fetch webapp 1 by page($page int!, $per page int!) { records( filter { table { value "webapp 1" } } page $page per page $per page ) { results { id properties } } } i'll use the following liquid to run this query when the endpoint page is accessed {% graphql fetch webapp 1 by page = "fetch webapp 1 by page" %} note i'll be using before and after my closing liquid tags to remove unnecessary whitespace from the results this is optional step 4) add liquid logic to handle incoming url parameters in the example, we'll pass inputs into the endpoint page using query parameters on the end of the url, for example, i already have the url for accessing the endpoint page /api/webapp 1 json remember the " json" extension should be replaced with the "format" you chose in step 2 i'll be storing the page i want to request from the endpoint in query parameters like so /api/webapp 1 json?page=2\&per page=1 you can now use context params `to read the url on the endpoint page and dynamically access each query parameter i'll store each in a variable before i feed these into the query, in case there is any type coercion to carry out first {% assign page = context params page %} {% assign per page = context params per page %} step 5) use liquid to feed variables into the query (and make sure they are the correct type) accessing these values via the above method tends to set them as string values in the variable for this example we'll need to change the type to integer as that's what the query expects you can refresh your knowledge on changing the type of variable in liquid in tutorial 6 {% assign page = context params page | add 0 %} {% assign per page = context params per page | add 0 %} we can then add them to the query {% graphql fetch webapp 1 by page = "fetch webapp 1 by page", page page, per page per page %} if the query expects variables to be strings you can actually add them straight to the query without assigning as variables first {% graphql fetch webapp 1 by page = "fetch webapp 1 by page", page context params page, per page context params per page %} step 6) output results on the endpoint page these will be the response body results are accessible via the variable name you defined in the graphql tag, but at this point we can decide on the format in which we'll display them option 6) a) html format if you decided in step 2 that you didn't want to change the page format, you should now build the required html structure you'd like to send back (this would probably be inserted as it is into a page via javascript) {% graphql fetch webapp 1 by page = "fetch webapp 1 by page", page context params page, per page context params per page %} {% for item in fetch webapp 1 by page records results %} {{item properties name}} {% endfor %} option 6) b) json format if you decided in step 2 to change the format of the page, you'll need to use liquid to output the content in this format as graphql already outputs in json format, this is easy {% graphql fetch webapp 1 by page = "fetch webapp 1 by page", page context params page, per page context params per page %} {{fetch webapp 1 by page}} option 6) c) csv format for something like csv, you'll need to use logic to output the data in the correct format this is just an example and you may need to alter it for your use case we use {% rather than {% in this example, because we want to preserve new lines to make sure each row of the csv displays correctly {% graphql fetch webapp 1 by page = "fetch webapp 1 by page", page page, per page per page %} name,id,description {% for item in fetch webapp 1 by page records results %}{{item properties name}},{{item id}}, {{item properties webapp field 1 1}} {% endfor %} step 7) test the endpoint page in your browser, visit the endpoint page url and see if the data displays as expected test changing the query parameters to see it change the returned data a successful json endpoint will return valid json in the body, as in the example here (other formats should also be checked for valid formats) {"records" {"results" \[ {"id" "220","properties" {"name" "we know guitar music" "slug" "we know guitar music" "enabled"\ true "og desc"\ null "og type"\ null "og title"\ null "meta desc"\ null "weighting"\ null "meta title"\ null "expiry date" 2145916800 "release date" 1570797009 "twitter type"\ null "category array" \[] "webapp field 1 1" "images/about/about 5 jpg" "webapp field 1 2" "man playing guitar" "webapp field 1 3" "we know guitar music" "webapp field 1 4" "lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua "}}]}} changing the url parameters should allow you to return different responses common issues your url should include the relevant file extension e g json for json format, csv for csv format if you are using html format, no extension is needed below is an example of a 404 response from using the incorrect extension your url should contain any query parameters you need for your query e g in my example, page and per page are mandatory below is an invalid response body resulting from missing url parameters congratulations! you've built a working get endpoint using graphql and liquid! the last two optional steps will expand upon your options for securing the endpoint and using the data available step 8) optional security and authorisation is your data sensitive and you want only logged in users to access it? is your data public and it doesn't need an additional authorisation step? this step shows you some different ways to make sure your data is secure, but you can skip it if your data is not sensitive or private option 8) a) using secure zones adding a secure zone to your endpoint page is a simple way to protect it from users and bots who should not be accessing it a failed access will still generate a successful 2xx response code, because it will succeed in returning html body (the 404 message that displays to users) this is only a problem if you're not using html format for your endpoint as it will cause any javascript which relies on parsing json to fail like so in step 9, you'll need to find a way to adapt your javascript logic to handle this kind of error which does not rely on the response code, but instead checks the response for the html tag \<h1>401 unauthorised\</h1> see step 9) a) i) and 9) a) ii) for examples of this logic option 8) b) using authorization policies you can use siteglide cli and platformos to build an authorization policy that checks the request either comes from a trusted site or from a trusted user the benefit of this is that it allows you to return http response codes as this is custom platformos code, it won't be covered by our support learn more about authorization policies on the platformos docs https //documentation platformos com/developer guide/authorization policy/authorization policy authorization policy tips these tips are intended as inspiration and do not constitute complete examples they do not require sending a query parameter over in your url, making them easier to keep secure if the user has been logged in (to any secure zone), you can check this on the endpoint page authorization policy {% if context current user id %} true {% endif %} to check that the request comes from an authorized page/ site, you can check this with context {% if context headers http referer contains "expected url" %} true {% endif %} step 9) optional get the data and use it on any of your other pages, you can now send requests to your new endpoint and fetch data for this you could use javascript the javascript examples provided here are intended for inspiration only unfortunately, we cannot advise you on how to adapt these to suit individual projects see the links at the bottom of this article for more resources you can use to help plan and develop projects of this kind example 9) a) i) logging json responses this basic example will request data from the example earlier and console log the response the if statement logic checks if a 2xx response code is received (meaning any authorization policies have passed) and that there is no html tag containing a 401 code from a secure zone check failure see step 8) for more details example 9) a) ii) parsing json and manipulating the dom in this expanded example, we'll fetch the data and then append it to the html dom add html and javascript an event listener targets the form and watches for a click event when the form is submitted, the event triggers the function "getwebappone" the if statement logic checks if a 2xx response code is received (meaning any authorization policies have passed) and that there is no html tag containing a 401 code from a secure zone check failure see step 8) for more details the function requests the data from our new endpoint it then loops over the items and appends each webapp name to the html dom get webapp names page per page get webapp 1 list of webapps \<script> var page = document queryselector('#page'); var per page = document queryselector("#per page"); var submit = document queryselector("#submit"); var output = document queryselector("#output"); function getwebappone() { event preventdefault(); var xreq = new xmlhttprequest(); xreq onload = function () { const checkforsecurezone = /401 unauthorised/g; if (xreq status >= 200 && xreq status < 300 && xreq response search(checkforsecurezone) == 1 ) { output innerhtml = ""; var jsonparsed = json parse(xreq response) models results; for(i=0;i\<jsonparsed length;i++) { console log(jsonparsed\[i] properties name) output insertadjacenthtml('beforeend', '\<div class="col">'+jsonparsed\[i] properties name+'\</div>'); } } else { console log('error', xreq responsetext); } } xreq open('get', '/api/webapp 1 json?page='+page value+'\&per page='+per page value); xreq send(); }; submit addeventlistener('click', getwebappone); \</script> example 9) b) requesting data from an html page in the previous two examples, we've used an endpoint with a json format endpoint you may find it easier to build html on the endpoint and when it arrives in the destination page, output it as it is build html on the endpoint page {% graphql fetch webapp 1 by page = "fetch webapp 1 by page", page page, per page per page %} {% for this in fetch webapp 1 by page records results %} {{this properties name}} {% endfor %} fetch html on the front end page a footnote your liquid endpoint page will be acting as an extra layer between your request and platformos' own graphql endpoint this extra layer is important because it allows you to run your own logic and security checks, before pos deliver the data related articles sitegurus have created the live updates api as part of the sitebuilder module designed as an incredibly flexible api endpoint for refreshing almost any siteglide layout with different filters this may save you time implementing your own api endpoint https //www sitegurus io/documentation/sitebuilder/live updates/introduction https //www sitegurus io/documentation/sitebuilder/live updates/introduction the siteglide support policy explains how you can get support with planning projects and writing custom code mdn have comprehensive documentation on the xml http request and how to use it in your front end javascript code https //developer mozilla org/en us/docs/web/api/xmlhttprequest you can also use the modern https //developer mozilla org/en us/docs/web/api/fetch api https //developer mozilla org/en us/docs/web/api/fetch api as an alternative those developers who prefer to use jquery when writing javascript can read more about ajax requests here https //api jquery com/jquery ajax/ platformos's documentation on pages includes lots of information about setting up pages using the yaml configuration https //documentation platformos com/developer guide/pages/pages