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.
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
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.
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.
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.
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’.
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.
2. Add your HERE developer keys into the APPLICATION_ID & APPLICATION_CODE section
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.
Autocomplete — HERE Geocode API
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.
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
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.
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:
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)
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?
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.
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.