Hands on

Getting Started with AWS Serverless Applications from HERE

By Michael Palermo | 10 January 2018

Recently at AWS re:INVENT, HERE announced the availability of ten applications through the newly launched AWS Serverless Application Repository. A serverless application makes it possible to manage an application feature as a configurable microservice. You can create and publish your own serverless applications for sharing, or deploy existing applications into your own environment. The applications featured in the repository from HERE align with many of our core APIs, such as geocoding, positioning, and routing. For an overview of the benefits serverless applications can bring to your overall solution, please take a few minutes to review the HERE segment of the AWS Serverless Application Repository breakout session from re:INVENT shown below.

This post will guide you through the process of discovering, selecting, and deploying the HERE Geocode Serverless Application for use in your development projects. Currently, the AWS Serverless Application Repository is in preview mode and you must sign up to request access to it. In addition to obtaining access to the repository, you will also need the following:

After signing up for a developer account at HERE, you will get access to APP ID & APP CODE values which are required to call HERE APIs. The AWS account is required to get access to all the developer resources at AWS, which includes the serverless repository (upon getting access to the preview).

One of the advantages of using a serverless application architecture is encapsulating application behavior in the Cloud and simplifying client logic and configuration. For example, as just mentioned, to use HERE APIs you must provide APP ID & APP CODE values from the calling client code. If you have an application that supports web and mobile clients, this would mean you need to configure each client to use your secret APP ID & APP CODE values. By using a serverless application, the APP ID & APP CODE values can be securely managed in the Cloud, and each client simply calls the serverless app via a custom API gateway. If that doesn't seem so simple, keep following along to see the implementation details.

Discovering AWS Serverless Applications

It should be noted that the output of a deployed serverless application produces AWS development resources that we are already familiar with. The core of a serverless application is AWS Lambda. In many cases, access to the Lambda will be accomplished via the Amazon API Gateway service. This means you could write your own serverless architecture from scratch. You could create your own Lambda, write all the code to call the HERE Geocode API, configure the APP ID & APP CODE values as environment variables used in the Lambda, and create your own API Gateway and configure it to trigger Lambda. Or... You could simply get all of that packaged together by choosing a serverless application as a starting point instead.

Because Lambdas play an essential role, this is where you will discover how to find existing serverless applications. In other words, to discover what serverless applications already exist, you start by creating an AWS Lambda. When you create a Lambda, you have three options for a starting point: Author from scratch, Blueprints, and now Serverless Application Repository. Note in the screen capture below, the Serverless Application Repository is selected, which is followed by a textbox search for "Geocode", which then produces the Geocode Serverless Application provided by HERE.

Typing values other than "Geocode" will show serverless applications related to whatever value you provide. You can also search for providers, such as "HERE Technologies."

Configuring an AWS Serverless Application

When creating a Lambda using a serverless application, you will likely get prompted for configuration information. In the case of all the serverless applications provided by HERE, the secret APP ID & APP CODE values are required up front as shown in following screen capture.

Once the values are all provided, you are ready to deploy the serverless application into your environment. But before we move on to that, consider the value being provided. The APP ID & APP CODE values entered will automatically be configured for you as environment variables to the resulting Lambda. The code produced in the Lambda will already be written to use these values for making HERE restful API calls. This is a huge time saver for developers!

Deploying an AWS Serverless Application

After clicking the deploy button, AWS goes to work and produces all the resources required to make the serverless application complete. By the way, this step can take a little time. Once finished, you should have results similar to the screen capture shown below.

The Geocode Servlerless Application provided by HERE supports two primary behaviors: geocoding and suggest. This results in the creation of two Lambda functions. In this post, we will focus on the core geocoding behavior. Now let's examine the default code provided in GeocodeFunction Lambda.


Consider lines 4 and 5 of the preceding code. These lines are using the the secret APP ID & APP CODE values provided during configuration which are now stored as environment variables.

How does this Lambda get triggered? By your newly created API already configured for you. At the AWS Console, search for API Gateway. You will notice you have new APIs. In the screen capture below, the Get method is selected for the /geocode API in Stage. In the resulting screen, the Invoke URL contains the specific URL your client code will need to call. Take note of the highlighted area below, as it will be different for you than shown here. That highlighted value will be needed in the next part of this post.

Using an AWS Serverless Application

For a simple demonstration of using the newly created serverless application, consider the following web client code:



On line 9 of the client, replace the { Your API } section with the highlighted value discussed in the previous section. Also observe the end of line 9, where the value "phoenix" is hard-coded into the URL as the search value. In this very simple HTML page, the goal is to call your custom API with the search value of "phoenix", and log to the developer console the JSON response. So if you intend to follow along in this post, you will need to toggle your browser's developer tools to display the console.

Upon running the page in your browser, you will likely see something not so friendly like the error shown here:

The short explanation for this issue is that CORS is not enabled on the client calling the HERE API. But wait, before thinking a change needs to be done to the HTML, ask yourself, 'Who is the client of the HERE API?' It is not the HTML, it is the Lambda code. So in order to support a web client, you need to enable CORS in the Lambda. Can you do that? Of course, and that is what is discussed next.

Modifying an AWS Serverless Application

Once you have deployed a serverless application into your own development environment, it is totally in your control. That means you can modify any aspect to suit the needs of your requirements. In the scenario provided in this post, you will need to modify the Lambda code shown earlier to enable CORS. To do that, find the line of code (line 32 shown previously) in the Lambda code that looks like this:

queryApi(url, (body) => { callback(null, { body: body }); });

And replace it with the following to enable CORS:


After making the change to the Lambda and saving it, rerunning the HTML page will now work without error. Remember, the only output of the demo is in the developer console.

Summary

In this post you learned about the AWS Serverless Application Repository. HERE is proud to be among the initial contributors to the repository, launching ten applications which map to core HERE APIs. You learned how to discover, deploy, consume, and modify the Geocode Serverless Application. The process shown in this post applies to the other applications provided by HERE in the AWS Serverless Application Repository. Happy coding!