Javascript API Updates 2014 - the migration guide

Find out if your outdooractive API projects need to be udpated and how to do it

As the outdooractive API continues to grow, we have made some important changes to improve the usability for developers. Please read this checklist to evaluate if your integration needs to be upated to be set up for the future. All API integrations that were implemented and launched before August 2013 will need to be updated. We are planning to shut down the old server and discontinue support of the old namespace by the end of 2014.

  • The outdooractive Javascript API is hosted under a new domain now
  • A new namespace was introduced
  • A new API key system was implemented
  • We have introduced new project keys

Please read the following checklist:

1. Check script tag (Javascript API)

Please check the script tag to find out if your integration loads the outdooractive javascript library from our legacy server. If you are already using our new FlexView API, you do not need to change anything as the FlexView API is already accessing data from the correct domain.

All outdooractive API projects that access the outdooractive javascript API from api.outdooractive.com in the following way:

<script
  src="http://api.outdooractive.com/alp.gmap.api/stable/dojo/dojo.xd.js?key=XXX-OLD-API-KEY-XXX"
  type="text/javascript"></script>

will need to be migrated to the new javascript libraries hosted under www.outdooractive.com as detailed below:

<script 
  src="https://api-oa.com/jscr/oax_head.js?proj=api-dev-oa&amp;key=yourtest-outdoora-ctiveapi&amp;lang=en&amp;leaflet_gshim=1"
  type="text/javascript"></script>

Please do not forget to add the project key as http get parameter proj. You always need a project key to integrate the new javascript library. The project key will set the project context on a page. As a result, you do not need to add the project key to the configuration objects of a ClusterLayer any more.

Please add parameter use_gmap=1 if you want to ensure that your integration will use the Google Maps API in the long run. The Outdooractive JavaScript API will be delivered using the Leaflet API by default soon.

<script 
  src="https://api-oa.com/jscr/oax_head.js?proj=api-dev-oa&amp;key=yourtest-outdoora-ctiveapi&amp;lang=en&amp;use_gmap=1"
  type="text/javascript"></script>

2. Check API key

The legacy API keys are long strings with numbers and lowercase characters. A legacy API key looks like:

1d71f0bbb133853e24a17a5797c0ab9b

Our new API keys are composed of three strings with eight characters each, separated by the character -. Uppercase characters and numbers are used. A new API key looks like:

XYZABCDE-KLMNOPQ4-7ZYWLVVZ

If you are still using an old API key, please get in contact with our project managers and they will send you new API keys. Our new API keys are bound to second level domains. This means you need a set of API keys if you have several customers and API integrations. Please list all domains that you use in production when you submit your API key request.

3. Check Project key

Some of the older API integrations are using ALPregio project keys that start with ar-. An ALPregio project key looks like:

ar-myproject

Since ALPregio and API projects are treated seperately now, all API integrations need to be migrated to API projects. Please get in contact with our project managers. They will create outdooractive API projects and send you the project keys starting with api- like:

api-dev-oa

4. Check Namespace

We changed the namespace from alp to oax. The main initialization function’s signature changed as well, receiving two parameters now. The first parameter is a reference to the outdooractive javascript API. The second one is a reference to the Maps API.

We use oamaps and gm as parameter names in all examples.

Your legacy integration might look like this:

alp.gmap3(function (gm) {

  // ...

  clusterLayer = new alp.gmap3.api.ClusterLayer( { proj : 'ar-oa-api', type : 'tour' });

  // ...

});

Please change the namespace, the initialization function’s signature, and for example, how layers are instantiated:

oax.api.maps(function (oamaps, gm) {

  // ...

  layer = new oamaps.ClusterLayer( { type : 'tour' } );

  // ...

});

The project key is not part of the configuration object anymore, as the project context is already set with the javascript library integration (see #1)

5. Check Guidelines

Please read our guidelines carefully and ensure that your integration complies with these rules.

Our guidelines ensure that copyrights of authors, content sources, photographers and map providers are respected and that content providers can get access to usage statistics.

We appreciate your cooperation.

Please get in contact with us if you have any questions about our API or the migration process described in this post. Your feedback is welcome.

Jens Schwarz