My development team at MapQuest builds APIs and SDKs for developers who want to use MapQuest services in their applications. When we are not creating new mapping and routing solutions, we focus on improving our current API set.
The Static Map API is used by MapQuest customers to retrieve a static map to display on a web page.
Recently we developed a new repeatable best practices process for refactoring. Our process included:
Step 1: Competitive Analysis
It’s important to first determine what your goal is and find out how you compare to your competitors.
Our goal was to find ways to make our API easier to use and faster to consume. We created a matrix comparing our Static Map API to similar APIs from other mapping vendors. This included a list of requested mapping parameters, standard parameter naming conventions, example code and the accuracy of documentation. The matrix was specific to this API. We reviewed the matrix with the entire development team to sketch out ideas. We were quickly able to identify areas of improvement in a one-hour meeting.
We were pleased to find that our API was still on parity with a rich feature set. Unfortunately, we learned that some of our parameter names were confusing and some of the documentation was unclear. For example, our API required three or more explicit parameters for a simple example on our “Try It Now” page. In contrast, many of our competitors APIs made a few basic assumptions and left many parameters optional. It was easier to get to “hello world” with our competitor’s solution.
Step 2: Remove the Junk DNA
We were looking for ways to make our API easier to use and faster to consume.With the competitive analysis in hand, we scrubbed the API for duplicate parameters. Duplicate parameters accumulate over time as features are added, often for specific customers or projects. A mature API tends to have a lot of parameters that seem to do the same thing.
We had two different commands to find the map center (pcenter and mcenter) and two ways to zoom (zoom and scale). By combining and documenting these features, we simplified the Static Map API without losing any features. We reduced the number of parameters while retaining full functionality.
Step 3: Rename Confusing Parameters
You don’t ever want confusion to be the barrier to people using your products.
The competitive analysis showed some of our API parameter names were different than parameter names used by other vendors for static maps, making it difficult for developers who are working with several vendors at the same time. We renamed several parameters to more standard terms to ensure a developer using several static mapping APIs from different sources would not be confused when making the same API calls.
Step 4: Review and Update the Documentation
Dot your I's and cross your T's.
We found many errors and artifacts in the old documentation. We updated the documentation and used this opportunity to reformat the documents into a more readable format with more code examples - an ask from our users. There are many open source tools available for documenting APIs. API Docs (http://apidocjs.com/) is a good example of a RESTful API documentation tool.
Step 5: Ship, Iterate, and Solicit Feedback
Testing is always good but soliciting feedback from those that matter is even more important.
Although our development team has expertise in mapping and routing, our customers are always using Static Maps in new ways. Once an updated API is released we post updates in user forums and blog posts. We also plan to streamline our release notes process so that customers can find all API updates at a glance.
We Will Do It Again
We found this process worked really well for us. This project also kicked off other ideas on creating more standardized and intuitive parameter names across all our API sets. We are releasing a new set of mobile SDKs for Android and iOS devices this month. We will use the same process to keep the SDKs up to date. We’re looking forward to seeing what new applications our customers create with our tools and incorporating your feedback to improve our offerings. Don’t hesitate to reach out with any suggestions you may have!
For more information on MapQuest APIs, SDKs, and other developer tools visit the MapQuest Developer portal and get a free key.