All organizations that have APIs, both internal and external, should be treating them as products. In keeping with that spirit, your API developer portal’s ability to showcase and explain your API can make or break its success. Your API portal is where current and future stakeholders will go to to learn everything possible about your API(s) and even your company. There are many facets that go into the leading API portals and ProgrammableWeb has created a series of articles that help you understand what best practices are being used by real-world API providers.
ProgrammableWeb kicked off this series with a comprehensive checklist of the criteria needed to build a world-class API developer portal. Subsequent Editors Choice articles including this one will provide a more in-depth look at how individual providers have executed on the various criteria. In some of these cases, we are looking at the overall portal while in others, we’re giving an Editors Choice for exceptional execution on specific criteria items.
When developers are starting to learn how to work with your API it is recommended to meet them where they are in terms of technology and language choice. One way a good portal does this is by offering resources in the form of SDKs and sample code in languages that are appropriate for developers. One often overlooked fact; in addition to ProgrammableWeb’s world famous API directory, we also run one of the worlds best SDK directories as well. The directory is filterable by language and API and each SDK in our directory is tied to its corresponding API in our API directory.
This article looks at TomTom, a location technology provider. TomTom’s developer portal does a terrific job of treating its SDKs as a first-class citizen on par with their API offerings.
Before reviewing how TomTom presents its SDKs, we should explain what SDKs are. In the context of the API economy, an SDK, or software development kit is a turnkey library of code that makes it easier for developers to code software applications with a specific language. Such SDKs relieve the developer from having to code low-level interactions with API endpoints often turning complicated API calls into simple functions that fit right in with the language they’re designed for. SDKs are an important tool when engaging with developers because they allow developers to work in the programming language they’re most comfortable with, thus flattening their learning curve when implementing an API. The SDK simplifies working with APIs by abstracting cross-cutting concerns (such as authorization, authentication, logging, and data transfer), thereby improving developer productivity, especially when creating new applications.
This disadvantage to SDKs is that they can add unnecessary bloat to the final application. Especially when the developer may only be using a small percentage of the overall SDK’s functionality for simple access to an API. In those cases, it’s sometimes better to work directly through the API by dealing directly with the API’s endpoint instead of through an SDK which essentially amounts to a translation layer.
The first time you land on the SDK page within TomTom’s portal, you see the difference in how TomTom promotes its SDKs versus the way most providers do. Many API providers are content to simply list the SDKs they offer (if the SDKs are offered at all) with links to their GitHub repositories. TomTom, on the other hand, gives the SDKs their own landing page, including an overview, use cases, and links to documentation and tutorials. It is almost like a portal within a portal.
Figure 1: TomTom gives its SDKs their own landing page, almost like a portal within the larger API portal.
In this review, we’ll walk through the documentation of the iOS SDK to give you a feel of how TomTom has organized the SDK section of its API portal. From the SDK page, if you click the link for the iOS SDK, you are taken to another landing page, this one for the iOS SDK.
Figure 2: The iOS SDK has its own landing page that helps give developers an overview of the content within.
Documentation for the iOS SDK contains a persistent navigation menu that contains links to each of the modules, a section on required downloads to start working with the SDK, release notes, and tutorials.
Figure 3: The navigation menu within each SDK contains links for each module, required downloads, release notes and tutorials.
The downloads section takes developers through the steps needed to make sure that the prerequisites are in place and they can begin coding with the SDK. This follows the best practice of reducing friction when developers are first using your API or SDK so that they can experience success as soon as possible.
Each module lets developers integrate data from one of TomTom’s APIs into their applications. Within the documentation for each module is a sub-navigation menu along the left-hand side. The sub-menus include links to a getting started section for integrating the module into a development environment, a documentation section that includes instructions on initializing the SDK, functional examples that help the developer understand how to implement the module’s features, and reference docs for the module.
Figure 4: Each module contains a sub-navigation menu to help orient the developer.
The Release Notes page shows notes on every update to the SDK since 2.0.1. This covers updates going back to January of 2018.
Figure 5: A full listing of release notes is included for all of the version 2 SDK releases.
One of the best parts of the SDK documentation are the tutorials included within each module. The Map module of the iOS SDK contains two tutorials, one to search along a route and the other to calculate the time to leave before proceeding to the destination point at the desired time. These are detailed tutorials that take the user step by step in order to build the sample application. Each one includes plenty of screenshots of the development environment (TomTom uses Apple’s Xcode IDE for its iOS tutorials) and the application at each step.
Figure 6: Each tutorial contains a number of screenshots throughout, including the Xcode IDE and step by step photos of the running application.
Better still, each tutorial contains all the sample code developers need to build the application. A number of API providers will include links to standalone sample code, hosted in a repository such as GitHub. These are fine, but to integrate the code samples within a complete tutorial adds more context and makes for better developer experience.
Figure 7: Sample code is integrated throughout the tutorials which gives greater context to developers.
By treating its SDKs as equals to its APIs, TomTom shows that it understands the importance of these tools to its developers. TomTom sends a signal that it will meet its developers on the platform where they are most comfortable. This is a way to market its SDKs and by extension, its APIs and it also helps to build trust that the SDKs will be supported in the future. For these reasons, TomTom has earned a ProgrammableWeb Editor’s Choice award for Developer Experience.