HERE APIs in a Serverless AWS App

Lynn Langit
Feb 11 · 8 min read

Written by Jessica Ellis & Lynn Langit

Learning API Programming

In the third episode of this series, we’ll walk you through a set of Codelabs which use HERE Technologies APIs to build a serverless web application, ‘Waterfall Express’. We’ll call the HERE Map, Geocode & Routing APIs — the latter via the AWS Serverless Application Repository. We’ll review the key steps so that you can understand and build this sample. To see what you are building, here’s a link to the completed Waterfall Express application.

The complete Waterfall Express Application

NOTE: There are even more detailed instructions in the associated three-part Codelabs — using Map, using Autocomplete, and using Routing. Also, for context, you may want to read the previous parts of this series — part one and part two.

The Serverless API-based Application

To start, you first publish a single-page serverless web application hosted in AWS S3. Then you add an interactive map to your application by calling the HERE Javascript Map API.

In the subsequent sections, you add autocomplete and routing functionality to your application map by invoking the HERE Geocode & Routing APIs via the AWS Service instances as shown below. You use the HERE AWS SAR Geocode and Routing applications to create these Lambda, API Gateway and IAM Role objects via CloudFormation templates. For more about HERE on AWS Serverless Repository — see this link.

AWS Serverless single-page web application architecture

Setup Services

To get started, you set up your service access. In order to build this example application, first you sign up to use the required services. For testing, you will likely be able to use the HERE Technologies and AWS FREE service tiers.

1. Create your developer account with HERE Location Services, Free Account.
2. Save your developer key values for use in your application.
3. Create your developer account with Amazon Web Services (AWS). Ideally you will use a dedicated account for training and development.

Setup AWS S3

Next you complete a couple of setup steps required to get the infrastructure to host a single-page website on AWS S3. The steps are summarized below:

1. Create a new AWS S3 bucket and set permissions
2. Upload the sample index.html file to S3
3. Configure the bucket properties to host a website

The data for your web application will be hosted via a publicly available AWS S3 bucket. AWS requires that you enter a globally unique name for your bucket. Enter a unique value in ‘Bucket name’ text box on the ‘Create bucket’ dialog box.

In order to set public access for the files in your bucket you perform two configuration steps. First, you uncheck all four boxes in the ‘Manage public access control lists (ACLs) for this bucket’ dialog box. This is found in the ‘Permissions’ tab of your S3 bucket properties.

Setting ‘public’ access on any AWS S3 bucket should only be used for training purposes.

Setting AWS S3 bucket access policy conditions

Next you add code on the ‘Permissions’ tab > ‘Bucket Policy’ section as shown below. This code sets the ‘s3:GetObject’ and ‘s3:ListBucket’ permissions to public access for your bucket. Note that your bucket name (lines 16/17 below) must be the unique name you gave to your bucket when you created it.

Custom AWS S3 bucket policy for public access

When you are done with these steps, view the bucket in the AWS console to verify that the ‘public’ label is associated with it, as shown above. To add the basic structure for your application, first you download the sample file index.begin1.html. Then rename your copy of that file to ‘index.html’. Next upload your local copy of your ‘index.html’ to your bucket.

To complete the last step to get AWS to host your application, you configure your bucket for static website hosting. To do this, in the console, for your bucket, click on ‘Properties’ > ‘Static Website Hosting’. In both the Index and Error text boxes enter “index.html”. Copy the generated endpoint value (example shown below), and click ‘Save’.

Configuring an AWS S3 bucket to host a website

Verify that your website renders as expected, by entering the generated endpoint URL in a browser. You should see the ‘Waterfall Express’ web page as shown below.

The Waterfall Express Serverless application

Add a Map — HERE Map JavaScript API

Now use the HERE JavaScript Map API to add a custom map to your application. To do this, open your local copy of the ‘index.html’ file and add JavaScript to add a dynamic map to your web page. There are three key steps to updating your code so that it calls the HERE Map API. This API returns a custom Map object which will be displayed as part of your web page.

1. Add references to the required HERE JavaScript files in the <Head> section of the page
2. Add your HERE developer keys into the APPLICATION_ID & APPLICATION_CODE section
3. Add the JavaScript to create our desired Map object. See the Map Codelab for specific detail on the code to add.

Save the updated, local file and then upload the updated file to your S3 bucket. In your browser, refresh the endpoint URL and click on “SHOW”. The HERE Map will now appear as shown below. The code you added sets the default location — with Iceland in the center of the displayed map. Test the interactive map by clicking on the map sizer tool (‘+/-’) and dragging the map.

Waterfall Express displaying a HERE Map

Autocomplete — HERE Geocode API

Next you will add autocomplete functionality (example shown below) to the location search text box in your application by calling the HERE Geocode API. Although you could use the same pattern (i.e. Javascript direct call in your ‘index.html’ file) as you did when calling the HERE Map API, you may want to use an alternative method to make your API call.

Waterfall Express using HERE Autocomplete for search

To efficiently call the API, AWS offers the AWS Serverless Application Repository (SAR). HERE Technologies has authored a number of applications to facilitate this process. Specifically, if you use the HERE Geocode Autocomplete SAR Application, you can implement this API call WITHOUT hard-coding your developer credentials into your application. The AWS HERE Geocode SAR application includes configurable parameters, designed to store calling credentials securely (shown below). In a previous part of this series, we covered this functionality in detail.

You will again add code to your local Index.html file. Then you’ll upload the updated file to the S3 bucket.

Storing HERE credentials in an AWS SAR Application

1. Update your ‘index.html’ file to add a JavaScript (jQuery) function to call the HERE Geocoder Autocomplete Javascript API directly.

2. Verify that the autocomplete functionality works.

3. Deploy an instance of the AWS SAR for HERE Geocoder. This creates a Lambda and API Gateway. It allows you to stores your HERE developer credential as AWS application parameters.

4. Update your index.html code to use the AWS endpoint to call the HERE API and remove the HERE developer credential key values from ‘index.html.’ Here are the summarized Codelab steps and a link to the detailed steps — found at Using Autocomplete.

5. Test your updated application

Using HERE Geocode AWS SAR Application

To use the AWS Serverless Application Repository to call the HERE Geocoder API, deploy the Geocode application. Use the AWS lambda console, click the ‘Create function’ button > ‘Geocode’, as shown in the screenshot above. The AWS SAR contains Cloud Formation templates, which are called applications, because they create one more AWS service instances. In this case, the HERE Geocode AWS SAR application creates a lambda, an API Gateway and an IAM role. The AWS Lambda console is shown below.

Working with Geocode Suggest AWS SAR application

Routing — HERE Routing API

In the third Codelab, you can use the pattern you implemented to add autocomplete to add another new feature to your application. You can add routing by calling the HERE Routing API from your application.

There is an AWS SAR for Routing, so you can add this feature quickly by implementing this development pattern:

1. Update your ‘index.html’ file to add a JavaScript (jQuery) function to call the HERE Geocoder Routing Javascript API directly.

2. Verify that the routing functionality works.

3. Deploy an instance of the AWS SAR for HERE Routing. This creates a Lambda and API Gateway. It allows you to stores your HERE developer credential as AWS application parameters.

4. Update your index.html code to use the AWS endpoint to call the HERE API and remove the HERE developer credential key values from ‘index.html.’ Here are the summarized Codelab steps and a link to the detailed steps — found at using Routing.

5. Test your updated application (an example is shown below)

Waterfall Express using HERE Routing

Here’s the complete code for ‘index.html’, you need to enter your HERE Developer credentials and your AWS API gateway endpoints in this sample to use it.

What did we learn?

In application development when calling APIs, sometime you’ll just want to call the HERE Technologies APIs using the JavaScript libraries. It’s quick and easy. However, a preferred pattern for production applications running on AWS which call HERE APIs is to use AWS SAR.

The reason for this are as follows:

— Secure storage of HERE Developer credentials as AWS application parameters (rather than hard-coded into source code)

— Simplified integration into AWS ecosystem via AWS Lambda and AWS API Gateway (== you write less code).

— Recommended patterns for using HERE Technologies for securely calling their APIs from AWS service instances.

Next steps

In the next installments we’ll be working with integrating HERE Technologies API with an a wider variety of AWS services, including voice-activated services and more.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade