In this tutorial,l you will learn about the two most popular techniques used for querying the Episerver content delivery API from within a SPA. Episerver has two samples site, the music festival site, and the foundation SPA site. Each call the content delivery API. Each sites slightly different technique to communicate with the content delivery API. In this tutorial, I will walk you through each one so you can decide how you which approach suits your needs the best.
First, let's start with the music festival sample site. If you load the music festival site and look within the network tab, you will see an XHR request is made to the content delivery API. This API call uses exactly the same page URL as the current page the only seemingly noticeable difference is a query string of
As shown above, the response to the site page with the
expand query-string returns JSON. If you try to add the URL directly within a browser then instead of seeing JSON the music festival site HTML will load instead. This is because the API will only be called when the
Accept header within the request is set to 'application/json'. You can prove this by opening up postman and calling
http://music-festival/?expand=* and setting you should get a response in JSON format from the API rather than the pages HTML.
Using the same URL definitely makes the network requests a little more user-friendly, however, it does have some downsides. First, it makes debugging a pain. If an error occurs on the production site then you will need to use Postman rather than a browser to get the JSON. Next, is caching. How do you cache things when the HTML and the API use the same URL?
To get around this problem you may be tempted to create an override to bypass the normal accept header check method and return JSON when a certain query string value eists. You could achieve this using a custom
ContentApiRouteService, like this:
This code will allow the content delivery API to be called when the
forceAPI query string is present. You can then register the
CustomContentApiRouteService within StructureMap like this:
If you now add the
forceAPI query string to the API request the JSON will now be returned. Armed with a bypass to return JSON from a web request it is easy to warm-up the cache and put expiry headers on the URL. From my experience with building React applications with Episerver, the preview functionality was a bit of a pain to get working when the HTTP and API URLs are the same.
Now let us compare this to how the foundation SPA works. The foundation SPA uses the non-friendly URL to call the API, like this:
This URL is viewable directly from a web browser. No extra code is required to make it viewable from a browser. You will not need to build a
CustomContentApiRouteService to access it. In fact within the music festival sample site, if you try to access the API directly it still works:
This approach allows you to have two public-facing URLs to access the same API. I tend to favor having a completely separate URL to access the content delivery API for a few reasons. First, it makes caching easier. Second, if you are building a multi-language website you do not need to worry about the language segment. Third, if you need to implement any preview or inline editing then the debugging will be easier. In fact, life becomes a lot easier when you differentiate the API URLs.
The approach you take is obviously up to you. From my experience using the same URL to access HTML and API causes more problems than it solves. Granted the URL is not as friendly when you use the API route however when things start to scale the extra confusion and trade-off do not really outweigh the benefits. Granted, either approach will work. If you want to make your life as simple as possible I recommend using the long API path.