Last year at the AWS re:Invent conference, HERE announced the availability of ten applications through the newly launched AWS Serverless Application Repository. At the time of the announcement, the repository was in beta and invite-only. Now any developer can deploy from many of the public applications availabe in the repository to quickly create a custom configurable microservice. For a bit more understanding of the benefits of the AWS Serverless Application Repository please visit our post introducing the HERE geocode service using the repository.
This post will guide you through the process of discovering, selecting, and deploying the HERE MapImage Serverless Application for use in your development projects. This will allow you to access custom map images from HERE via your own custom API. To accomplish this, you will need credentials at the following:
- A developer account at http://developer.here.com - now featuring our new freemium plan!
- An AWS account at http://aws.amazon.com
Discovering the HERE MapImage Serverless App
After account credentials are confirmed, to find the HERE MapImage application, browse to the AWS Serverless Application Repository.
After clicking the "Browse all applications" button, you will be prompted to do your search. Type "HERE MapImage" as shown below, then select the MapImage title in the results shown.
The landing page for the MapImage application is shown. You are now ready to deploy.
Deploying the HERE MapImage Serverless App
What does deploy mean in this context? It means installing in your AWS environment all the code and resources needed for you to manage your own serverless app. Once the HERE MapImage application is deployed, it is now your serverless app. Deployment is so easy! Just click the "Deploy" button to start the process.
You will prompted to provide three values.
You can name the application whatever you choose - just know it is used to help identify resources related to your custom serverless app. The "HereAppCode" and "HereAppId" fields are filled with values you receive from your HERE developer account. Once the fields are filled in, click the "Deploy" button. It will take a little time for the deployment process to complete. The process is finished once you see the "Application successfully deployed!" message as shown here.
In the resource list shown in the right panel, click on the "MapImageFunction" link. This will take you to the underlying lambda created. Once there, you are ready for the next step.
Configuring Your Map Image Service
As mentioned before, now that the MapImage application and related resources are now deployed in your environment, you are in total control of what do do from here. Techncially, you wouldn't need to do anything else to start using the service, as long as your client is not a web page. However, since this post will show how to call your custom map image service from a web page, it provides an opportunity to explore some of the resources deployed into your environment.
From the previous step, you should be on the landing page for the custom "MapImageFunction" lambda. Near the top of the page, you will notice a visualization of the associated triggers and resources.
The only trigger for the lambda is the API Gateway. In other words, it will be a call to your custom API that will trigger the code in the lambda. What does your custom API look like, and how can you call it from a client? To observe what was created for you, click on the "API Gateway" box in the visualization.
You will see the API Gateway results appear on the page. If details are collapsed, expand them to view everything. For your benefit, copy the URL designated as the API endpoint and save for a future step. The API endpoint URL is used by client apps to call your custom map image service. Once you have copied the URL, click on the link residing above the details.
On the page for the API Gateway, make sure the section selected on the left side is "Resources", and the root node "/" is also selected. Next, click the "Actions" drop down menu. Click on the "Enable CORS" menu item. Accept the default prompts, and return to the "Actions" menu. Now click the "Deploy API" menu item. If prompted to what environment to deploy to, choose "Prod" for now, since the API endpoint URL copied earlier resides there. The redeployment takes very little time, and you are now ready to test.
Consume Your Map Image Service
Listed below is the HTML client in it's entirety:
Take note of line 11. You will need to replace the value with the data you have in your API Gateway endpoint URL copied earlier. Line 12 concatenates query string parameters to indicate coordinates [c], width of image [w], height of image [h], and zoom level [z]. Lines 14-22 make an asynchronous call to your custom API and return the results. Because the data returned is base64 encoded, it is designated as such with the data moniker shown on line 18. Executing the page results with an image! In this example, getting a view of the author's hometown.
Summary
HERE is proud to be among the initial contributors to the AWS Serverless Repository - launching ten applications which map to core HERE APIs. In this post, you learned how to discover, deploy, configure, and test your own microservice derived from the HERE MapImage serverless application. In upcoming posts, we will explore how to use some of the other serverless applications provided by HERE.
For a recap of the benefits of deploying a application from the serverless repository, plese view the segment from the AWS RE:invent session below:
