1. Home
2. Solutions
3. Tutorials

While the view layer of the web consists of HTML, CSS, and JavaScript, much of the data you want to present to your users is better represented and exchanged using formats like JSON. Generally, data is interpolated into a template within the core infrastructure of an application and then the HTML can be cached at the edge. In this tutorial you can learn how to move the templating process to the edge, allowing your core application to focus on pure data.

This tutorial documents the creation of a fast, personalized weather dashboard powered by Fastly's geolocation API and WeatherAPI, a provider of weather data in partnership with governments and meteorological agencies around the world. Later in the guide, you will create a free WeatherAPI account and get your own API token to retrieve weather data.

You can see below exactly what you will be building:

WeatherAPI.com

WeatherAPI provides the Forecast API endpoint where you can send requests with the latitude and longitude coordinates of any place in the world, and receive JSON-encoded weather information for that location. This is ideal for a basic weather app, and can be combined with the Fastly geolocation API to fetch weather information for the location associated with the end user's IP address.

You will integrate with this later, but for now let's look at an example request and response from the Forecast endpoint:

Current weather data

curl -L -X GET 'https://api.weatherapi.com/v1/forecast.json?q=51.521,-0.136&days=4&key=4f6b298d55504374b78203319220712'

{
    "location": {
        "name": "London",
        "region": "City of London, Greater London",
        "country": "United Kingdom",
        "lat": 51.52,
        "lon": -0.14,Show more

Instructions

Initialize a project

If you haven't already created a Rust-based Compute project, run fastly compute init in a new directory in your terminal and follow the prompts to provision a new service using the empty Rust starter kit:

$ mkdir weather && cd weather
$ fastly compute init

Creating a new Compute project.

Press ^C at any time to quit.

Name: [weather]
Description: A weather dashboard served at the edge
Author: You!
Language:
[1] Rust
[2] JavaScript
[3] Go
[5] Other ('bring your own' Wasm binary)
Choose option: [1]
Starter kit:
[1] Default starter for Rust
    A basic starter kit that demonstrates routing, simple synthetic responses and
    overriding caching rules.
    https://github.com/fastly/compute-starter-kit-rust-default
[2] Empty starter for Rust
    An empty starter kit project template.
    https://github.com/fastly/compute-starter-kit-rust-empty
...
Choose option or paste git URL: [2]

Install dependencies

When the JSON response comes back from WeatherAPI, you'll need something to parse it so that you can use the values in your template. serde is a Rust crate that provides serialization and deserialization for common data formats like JSON.

To generate the view that will be sent to the client, you will need a templating library. For the purposes of this tutorial we suggest tinytemplate.

Add these dependencies to your Cargo.toml file:

7 lines
serde = { version = "^1.0.149", features = ["derive"] }
tinytemplate = "^1.2.1"
1 lines

You will also need a helper data structure specific to this tutorial. We have packaged this into a Rust crate that you can include in your project:

9 lines
weather_demo_helpers = "^0.1.1"

Use the WeatherAPI backend

Obtain an API token

To use the free plan of WeatherAPI, you will need an account and API key. Head to the sign up page and enter your details. Follow their instructions to activate your account.

Head to your dashboard and copy the API key that has been generated for you. You will need to add this key as a property named key to an edge dictionary (also known as a Compute Config Store) named weather_auth on your Fastly service, which you will use in the program next to securely fetch the API token. You can do this however you prefer:

• Via the web interface
• Via the API
• Via the CLI, using the fastly dictionary create and fastly dictionary-item create commands

Fetch the API key

Remove the contents of the main method generated by the empty starter kit, and write a method to retrieve the API key you added to the Config Store (dictionary) earlier:

1 lines
use fastly::ConfigStore;
110 lines
/// Retrieves the WeatherAPI key from the "auth" Comput@Edge Config Store.
fn get_api_key() -> String {
    match ConfigStore::open("auth").get("key") {
        Some(key) => key,
        None => panic!("No WeatherAPI key!"),
    }
}

You will use this method later to generate an API request to WeatherAPI.

Match the request route

This tutorial will serve the generated HTML, stylesheets, and images from the same Compute service. To achieve this, you can use Rust's pattern syntax to execute different logic based on properties of the incoming request, such as the path. Write some basic routing code inside your now-empty main function:

6 lines
// We provide helpful constants for HTTP methods, headers, status codes, and more:
use fastly::http::{Method, StatusCode, header};
9 lines
/// The entry point for your application.
#[fastly::main]
fn main(req: Request) -> Result<Response, Error> {
    // Return early if the request method is not GET.
    if req.get_method() != Method::GET {
        return Ok(Response::from_status(StatusCode::METHOD_NOT_ALLOWED));
    }
    let resp = match req.get_path() {
        // Serve the weather widget.
        "/" => {
37 lines
        }
        // Serve static assets.
8 lines
        // Catch all other requests and return a 404.
        _ => Response::from_body("The page you requested could not be found")
            .with_status(StatusCode::NOT_FOUND),
    };

    Ok(resp)
}
38 lines

Fetch the weather data for the user's location

Using Fastly's geolocation API to fetch the user's latitude and longitude will give you all the data needed to construct a request to WeatherAPI. Add the imports and BACKEND_NAME constant as shown below, and the logic within the "/" branch of the match clause to make a request to the backend you defined earlier:

2 lines
use fastly::geo::{geo_lookup, Geo};
6 lines
// Define a constant for the backend name:
const BACKEND_NAME: &str = "weather_api";
14 lines
        // Serve the weather widget.
        "/" => {
            // Get the end user's location.
            let location = geo_lookup(req.get_client_ip_addr().unwrap()).unwrap();
            // Log output helps you debug issues when developing your service.
            // Run `fastly log-tail` to see this output live as you make requests.
            println!(
                "Requesting weather for {}, {} ({}, {})",
                location.latitude(),
                location.longitude(),
                location.city(),
                location.country_name()
            );
12 lines
            // Build the API request, and set the cache override to PASS.
            let url = format!(
                "http://api.weatherapi.com/v1/forecast.json?q={},{}&key={}&days=3",
                location.latitude(),
                location.longitude(),
                get_api_key()
            );
            let bereq = Request::new(Method::GET, url).with_pass(true);
            // Send the request to the backend.
            let mut beresp = bereq.send(BACKEND_NAME)?;
4 lines
        }
54 lines

If you look at the JSON response from WeatherAPI, you'll see that it contains a lot of data you don't need for the weather dashboard – and also that it doesn't contain some elements you do need, like the names of weekdays, or today's date in a friendly format.

💡 The take_response_body method of the Fastly Response struct takes a custom return type which can be used to deserialize the JSON response body. You can either define your own type to represent the data you need for the dashboard, or use one from the weather_demo_helpers crate that accompanies this tutorial, to save time.

Import the ForecastAPIResponse struct from the helper crate, and pass it to the take_response_body method:

3 lines
use weather_demo_helpers::ForecastAPIResponse;
54 lines
            // Send the request to the backend.
            let mut beresp = bereq.send(BACKEND_NAME)?;
            // Parse the response body into a ForecastAPIResponse.
            let api_response = beresp.take_body_json::<ForecastAPIResponse>()?;
57 lines

👉 Under the hood, ForecastAPIResponse performs sophisticated transformations on the JSON response – for example, by converting timestamps to weekday names, or weather conditions to the names of Material symbols – thanks to the serde framework. The final data structure contains all the variables you need to power your dashboard:

ForecastAPIResponse {
    at: LocationData {
        location: "London",
        dt: DateElements {
            weekday: "Thursday",
            weekday_short: "Thu",
            pretty_date: "8 December 2022",Show more

At this point, visiting your application's domain will fetch your weather info, but will not yet return it to your browser. You'll fix this in the next step.

Generate HTML using a template

This tutorial uses the tinytemplate crate to interpolate dynamic weather data into a static HTML template. You'll need to define a serializable type for the data you will pass to the template, and a method to generate HTML from the data.

4 lines
use serde::{Deserialize, Serialize};
use tinytemplate::TinyTemplate;
19 lines
        // Serve the weather widget.
        "/" => {
35 lines
            let body_response = generate_view(api_response, is_metric);
            Response::from_status(StatusCode::OK).with_body_text_html(&body_response)
        }
23 lines
/// Context for TinyTemplate
#[derive(Serialize)]
struct TemplateContext {
    weather: ForecastAPIResponse,
    is_metric: bool,
}
1 lines
/// Generates an interpolated HTML string with TinyTemplate.
fn generate_view(
    api_response: ForecastAPIResponse,
    metric: bool,
) -> String {
    // Initialize the template.
    let mut tt = TinyTemplate::new();
    tt.add_template("weather", include_str!("static/index.html")).unwrap();
    // Define the template context.
    let context = TemplateContext {
        weather: api_response,
        is_metric: metric,
    };
    // Render the interpolated template string.
    tt.render("weather", &context).unwrap()
}
8 lines

If you'd like to use the static/index.html template and other assets from this example, download static.zip and extract it in the src folder of your project. Otherwise, feel free to build your own frontend starting from the TemplateContext data structure.

Serve static assets

Your dashboard should now load and show your current weather! It doesn't look that good though, so you will need to set up a route to serve your stylesheet:

65 lines
        // Serve static assets.
        "/style.css" => Response::from_body(include_str!("static/style.css"))
                .with_content_type(fastly::mime::TEXT_CSS),
51 lines

Next, set up some routes to serve the background images from the asset bundle, and avoid repetition by writing a function that constructs image responses:

65 lines
        // Serve static assets.
2 lines
        "/img/snow.jpg" => image_response(include_bytes!("static/img/snow.jpg")),
        "/img/rain.jpg" => image_response(include_bytes!("static/img/rain.jpg")),
        "/img/cloud.jpg" => image_response(include_bytes!("static/img/cloud.jpg")),
        "/img/fog.jpg" => image_response(include_bytes!("static/img/fog.jpg")),
        "/img/lightning.jpg" => image_response(include_bytes!("static/img/lightning.jpg")),
        "/img/sunshine.jpg" => image_response(include_bytes!("static/img/sunshine.jpg")),
7 lines
/// Returns an image response from a byte slice.
fn image_response(bytes: &[u8]) -> Response {
    Response::from_body(bytes)
        // Add a long cache header to the response.
        .with_header(header::CACHE_CONTROL, "public, max-age=86400")
        .with_content_type(fastly::mime::IMAGE_JPEG)
}
31 lines

Switching units

Your Compute service will be deployed globally. Some users will expect to read temperatures in °C (the metric scale), and others in °F. It's a good idea to default to a scale based on the end user's location, but also to provide a way to switch units.

To achieve this, you can read a query string parameter, metric, to determine the desired scale based on user input. If this parameter is not present:

1. Use the country_code method from Fastly's geolocation API to get the 2-letter country code associated with the user's IP address.
2. Unless the user is in the United States, the Bahamas, the Cayman Islands, Liberia, Palau, Micronesia, or the Marshall Islands, default to the metric scale to display temperatures.

12 lines
#[derive(Deserialize)]
struct QueryParams {
    metric: Option<bool>,
}
22 lines
            // Parse the query string into the `QueryParams` type.
            let query: QueryParams = req.get_query()?;
            // Decide whether metric units should be used, based on the
            // `metric` query param, falling back on the user's country code.
            let is_metric = match query.metric {
                Some(metric) => metric,
                None => match location.country_code() {
                    // Countries that use the non-metric Fahrenheit scale
                    "US" | "BS" | "KY" | "LR" | "PW" | "FM" | "MH" => false,
                    _ => true,
                },
            };
69 lines

The "Switch units" button in the example template should now work as intended. Clicking on this button will reload the page with the metric query parameter set to the opposite of its current value.

Build and deploy

Congratulations! You now have an elegant weather dashboard that can run at the edge. If you haven't yet, run fastly compute publish to build and deploy your service to the Fastly network. When prompted, enter api.weatherapi.com as the backend hostname:

$ fastly compute publish
✓ Initializing...
✓ Verifying package manifest...
✓ Verifying local rust toolchain...
✓ Building package using rust toolchain...
✓ Creating package archive...

SUCCESS: Built rust package weather (pkg/weather.tar.gz)


There is no Fastly service associated with this package. To connect to an existing service
add the Service ID to the fastly.toml file, otherwise follow the prompts to create a
service now.

Press ^C at any time to quit.

Create new service: [y/N] y

✓ Initializing...
✓ Creating service...

Domain: [random-funky-words.edgecompute.app]

Backend (hostname or IP address, or leave blank to stop adding backends): api.weatherapi.com
Backend port number: [80] 443
Backend name: [backend_1] weather_api

Backend (hostname or IP address, or leave blank to stop adding backends):

✓ Initializing...
✓ Creating domain 'random-funky-words.edgecompute.app'...
✓ Creating backend 'weather_api' (host: api.weatherapi.com, port: 443)...
✓ Uploading package...
✓ Activating version...

Manage this service at:
        https://manage.fastly.com/configure/services/PS1Z4isxPaoZGVKVdv0eY

View this service at:
        https://random-funky-words.edgecompute.app


SUCCESS: Deployed package (service PS1Z4isxPaoZGVKVdv0eY, version 1)

Next Steps

Now that you understand how to make your program act on geolocation data, why not use this to select an appropriate default unit based on the user's locale?

You could also try improving the logging provided in the tutorial, using the log-fastly crate. This allows you to log data to any of Fastly's supported logging backends.