Select Page

Sarah Habershon was having a few issues getting data from the Geonet API for her recent visualisation on the shaky times we have been having in NZ. Turns out the Geonet API does not allow direct cross-origin resource sharing, so we had to get around that!

Cross-origin resource what?

Cross-origin resource sharing is a system where one web page can use resources provided by another server, or “origin”. Most server systems dont allow this by default, including geonet. To get around this we need to create a API proxy that does allow CORS access. This works by forwarding the query through our API to the Geonet API and then returning the result to the original requester.

A great way of doing this is with AWS API Gateway. With API Gateway we can proxy API request to another HTTP endpoint with no need for servers or scaling.

Lets do it!

To do this with AWS API Gateway we need access to the AWS Console with rights to be able to create AWS API Gateways!

Creating a API Gateway

1 – Browse to the AWS API Gateway Console
2 – If you have not created a AWS API Gateway before we will need to hit the getting started button, otherwise hit Create API
3 – Select New API at the top, name our API something relevant, and give it a nice description.
eqapi-1
4 – Click “Create API”

Cool now we have a nice blank API to build upon. We now need to create a method that will route a request to Geonet.

Creating Methods

We will start on the resources screen of the API Gateway we just created

1 – Click Actions
2 – Select “Create Method” from the dropdown.
eqapi-2
3 – In the white box created by the last step select GET, and click the tick
eqapi-3
4 – Select HTTP as our Integration type
5 – Enter the HTTP url of the API we want to route, in this case it is “https://api.geonet.org.nz/quake”
6 – Content Handing should be set to “Convert to text (if needed)”
7 – Click “Save”

Cool, we have created a method in our API! Now we need to route our parameter though to the Geonet API!

Routing Query String Parameters

Sarah is only interested in Earthquakes of a magnitude of greater than 2 so we need to allow her to pass that section of her query through to the Geonet API. If we were doing this with raw HTTP the query url would look a little like “https://api.geonet.org.nz/quake?MMI=2”. We just need to map this MMI though our query.

We will start from the GET query execution management page that we left the last step on.

1 – Click on Method Request
2 – Drop down the URL Query String Parameters section
3 – Add query string
4 – Enter “MMI” as the name
eqapi-4
5 – Click the tick

We have just specified that we can handle MMI as a variable on our incoming query, now we need to map this to our outgoing query.

1 – Return to the Method Execution management page
2 – Click on Integration Request
3 – Dropdown the “URL Query String Parameters” section
4 – If an entry for MMI is already there then it has been created for us (skip the last steps), otherwise create a new entry
5 – Name our entry “MMI”
6 – In mapped from enter “method.request.querystring.MMI”

We have now mapped our MMI variable through to the Geonet API. Time to test its all working!

1 – Return to the Method Execution management page
2 – Click “TEST”
3 – Enter “2” as the value for MMI
4 – Click Test

We should now get some data back about recent earthquakes.

eqapi-5

If you get something else, go back and make sure you didn’t skip any steps!

Enabling CORS

So we have our API be able to direct request to the Geonet API, but our API is also set to not allows CORS request. A quick fix it needed.

1 – From the API Resources management page click the Actions dropdown
2 – Select  “Enable CORS”
eqapi-6
3 – Leave all the options as default and click Enable CORS and replace existing CORS headers
4 – On the next screen select “Yes, replace existing values”

We have now enabled CORS, time to publish our API.

Publishing our API

We now have an API, time to publish it so that Sarah can use it from her webpage. AWS API Gateway uses to concept of stages to isolate changes to certain environment. This allows you to have a production and development API from the same console.

1 – From the API Resources management page click the Actions dropdown
2 – Select Deploy API
eqapi-7
3 – Select “New Stage” in the Deployment stage box
4 – Name our stage something relevant
5 – Give it a nice description
6 – For the Deployment description, we can either use an english description of what we are doing or a version number
eqapi-8
7 – Click “Deploy”

We have now published our API! On the screen it sent you to we now have a URL which we can provide to Sarah and she can use it to query Geonet through our API!

eqapi-9

Example of a query:
eqapi-10

Hope this helps with your API CORS needs!

Coffee to Code – Tim Gray

Tim blogs about the sharp end of code and the languages it is written in.

You can read Tim’s RESTful API series here or all of Tim’s blogs here.

%d bloggers like this: