The ABCs of building API developer portals

On the main website of a business, the developer portal is usually listed in the footer and header menus. It is common practice to use a subdomain with a nomenclature like developer.domain.com or developers.domain.com to host a developer portal. But there are plenty of portals that go the route of domain.com/developers as well.

A developer portal may start off as a documentation repository, but should grow into a full community site with the sorts of tools and assets that have been described in Part Ten: How To Build Great API Developer Communities At bare minimum, this should include (but is not limited to):

• Terms of Service and Service Level Agreement
• Engaging documentation with interactive consoles and sandbox testing environments
• Code snippets and code for a sample application in a variety of languages that match your target. For example, if server-side developers are going to be the primary consumers of your API, then samples in Node, Python, Java, and other server-side environments make the most sense.
• Self-serve API registration
• A public-facing API specification format file using the commonly accepted Open API Specification (OAS) or other human- and machine-readable metadata about your API.
• An interactive API console that can show sample responses from each of the API's resources
• A developer playground (often driven by an "API mocking service") that developers can sample with their own code
• API uptime status page
• Pricing plan page
• Support forum
• Online chat
• SDKs and API wrappers
• Developer community marketplace or showcase of created apps and expert developers
• Step-by-Step Tutorials

Some API providers have both marketing and technical writing specialist skills involved in the creation of content on their developer portal. If your API strategy is successful, your sales, customer support, and customer success teams will need to be comfortable with accessing your developer portal and API documentation. Having a good writing team involved in creating and maintaining your developer portal will widen the scope of the target audiences that can make use of your developer portal.

Cities and governments may have departments and agencies creating APIs. Part Three: What Data and Services Should Your API Expose First? looked at what data and services cities and governments are already opening up by API. The problem with this approach is that cities and governments are poor creators of developer portals. It's often left to the individual agency to create the developer portal. That means a developer needs to have a strong understanding of the government department's structure, and which agency would have responsibility for which dataset or government service delivery function.

Other governments and cities use open data portals to list all of their APIs. Sometimes this may include design-crafted APIs for a particular data asset or service, but more often the list tends to reflect APIs that are created automatically from datasets stored on an open data portal. The problem with this is that the APIs are often created for pilot or limited use as another mechanism of exposing the data rather than as a fully product-managed API that sits within an API strategy. As a result, the APIs may have strict limitations on the level of use that they allow or may be so tied to a particular dataset that they are not updated and maintained regularly, reflecting a static, point-in-time dataset.

Many government and city developer portals demonstrate the limited uptake of APIs. In addition, these portals often show the lack of strategic thought within city management and governments to encourage API usage as a way to understand local communities or as a way to transact and engage with government departments, cities, and agencies.

As traditional industries move towards opening up APIs and creating new platforms for external developers, there is a growing need for organizations to create centralized developer portals that encourage external digital startups to build new commercial assets. Logistics, airlines, banks, packaging, and insurance are just some of the more traditional industries that are now beginning to open up APIs to allow partners and customers to integrate directly to business services and data assets. In some industries like banking, there is also a push to drive a FinTech sector that is building a new wave of applications on top of banking APIs.

But many of these traditional industries are weak at creating great developer experiences. The global logistics company Maersk, for example, has a developer landing page that lacks any inspiration, that includes a prominent but inoperable button to obtain an API key, and that does not provide detailed information on potential use cases for its APIs. The company also fails to provide agreement details for third parties building on its APIs and has a complicated site navigation system. Maersk's page is unclear whether these APIs are fit for production use at this stage.

UPS provides a fairly antiquated style of developer portal, with at least a brief sentence or two about the use cases that align with its APIs. This gives developers some idea of whether they want to use the API in their applications or business processes. But to review the API documentation, a developer must sign up first to an account. However, after signing up, the new user is sent back to the UPS Post enterprise home page, which has no link to the developer portal! Finally, after navigating back to the developer page, users will find that although some of the use case information on APIs is better presented, the documentation for each API is only available as downloadable ZIP files that contain PDFs.

Airlines are getting better at engaging developers through the portal experience. Lufthansa has a developer portal where developers can make mock API calls through a sandbox functionality, review API reference documentation, use an innovation hub that helps developers discuss their ideas. The portal includes an API status page to show the uptime and performance of the airline's APIs. The company offers engagement through Stack Overflow and Twitter, and it has prepared a landing page to showcase apps built off its APIs. Lufthansa does have a partner sign-up process required before users can build anything with its APIs, although developers can use the public plan to make a limited number of calls while in product development stage. Accredited developers will gain 1.5% revenue from each successful booking made via their APIs as part of a developer shared revenue/affiliate business model. Lufthansa's developer portal, while not the prettiest, does include a wide range of best practice resources that can help onboard developers and encourage them to start building with clarity.

Given the increasing competition globally amongst banks to open APIs, banking developer portals vary widely with regards to quality. Sites like Capital One and Mastercard offer individual landing pages for each of their APIs that describe the use cases for each API, the business/pricing model, Getting Started guides, and tutorials. Developers can test APIs without registering, and if they do register, they can start integrating and building their application before submitting their product for final approval. Other banks like Westpac in Australia offer an API for credit card payment processing. While its developer portal includes an overview of the functionality of its API and video tutorials, additional information is only accessible via a PDF, and developers must make contact using email to be given access to the API or the top view of any documentation.

Software-as-a-Service (SaaS) businesses are greatly motivated to create and provide APIs to third parties. APIs for SaaS tools help drive new customers to the main product and can increase the stickiness of existing customers. For example, dev tools software provider Atlassian offers Confluence, JIRA and HipChat as developer tools for building applications. But it also has a set of APIs that allow other startups and businesses to create new apps that provide additional functionality to Atlassian's core suite . (The same is true for financial accounting service QuickBooks , and business software provider Zoho . Both services have core products and APIs that let other startups build new apps that offer additional functionality on top of their SaaS core product.)

In fiscal year 2017 alone, apps built using Atlassian APIs have generated $100 million in revenue, of which Atlassian receives 25% through revenue sharing with app builders. In addition, the company's own customers who use at least one external app have a 10% higher customer retention rate than Atlassian users who don't use any third-party apps.

SaaS providers publishing APIs need to keep these business models in mind and seek to make sure that their websites support external developers to grow their own business. This means having marketplaces where third parties can market the apps they build, provide clear pricing and revenue-sharing details, offer an API uptime status page, and use engagement opportunities like an engineering Twitter account to help devs connect quickly and resolve problems.

In our focus on developer documentation (Part nine: Best Practices and Tools for Documenting APIs), we reviewed some of the tools that can help API providers quickly build and customize engaging API documentation, including code snippets and in-documentation sandboxes. Tools also included document search plugins and documentation auto-generators that could create reference materials based off an API specification file.

While good documentation is table stakes for growing an effective developer community, the additional developer resources outlined above are equally as important. We have identified the tools described below as available templates that offer a way to collect and publish a more extensive range of resources for developers.

API management providers all provide some level of templated developer portal. For many API providers, these templates may be sufficient for providing all of the developer resources necessary to start building a community. But for API providers seeking to offer a rich selection of resources and engagement opportunities, and that want to customize their developer portal to best reflect the developer community audience segments they have identified, they may find it useful switching to an independently developed portal. But, doing so also introduces its own integration issues, such as making sure that developers have a backend analytics dashboard where they can see which APIs they have keys to, and can track their consumption and perhaps other data such as API performance or error rates.

Ultimately, the choice to buy or build depends on a variety of factors; the needs of the organization, the suitability of existing solutions to those needs (and how flexible those solutions are in terms of customization), and the organization's tolerance for building, maintaining, and supporting a custom solution (an endeavor that's not to be underestimated).

The developer portals listed below all have:

• Clear onboarding workflows for new developers
• Links to documentation
• The capacity to integrate with metrics that allow API providers to see statistics on the pages developers accessed and whether they registered for an API key
• Menu options for additional resources, such as community forums, FAQ pages, example apps, and contact information

Created by the U.S. General Services Administration's 18F agency, this template provides a simple developer hub prototype for use by any agency to list their APIs and interact with developers. This prototype is used by U.S. government agencies who need to create developer portals to engage developers with their APIs. The U.S. Department of Trade , for example, used this template to attract and engage with developers.

Acquired by Mashape, Gelato is a Developer-Portal-as-a-Service tool with API registration, sandbox explorers, documentation, and automatic generation using API specification formats. Gelato is not a self-serve option, however, and interested API providers need to contact the Gelato sales department for details of pricing and capacity of the platform to integrate with existing API management providers. Gelato currently appears to be pivoting towards being an enterprise solution for companies already using other Mashape API tools, such as the open source API gateway Kong .

In addition to their documentation product (see Part 9), ReadMe also offers a fully fledged Developer Hub template, called Hootr, which lets API developers include documentation, reference material, code snippets, and community support forums. Hootr is a very basic, bare-bones option for developer portals, and it is without the design aesthetic that makes Readme so appealing. It operates similar to a WordPress template: Hootr has all the sections like API signup, community forum, and a developer comment feed similar to social media feeds. Bizarrely, there is no standard footer for documents like terms of service or privacy policies. It appears that Hootr is more of an MVP at present, while the main work is still done on managing readMe as a Documentation-Tool-as-a-Service product. It appears that API providers must have a ReadMe account to be able to use Hootr, although implementation details are sparse on the website. One service that is using Hootr as its developer portal is the serverless microservices product nanoscale.io (recently bought by TIBCO).

While originally created as another Portal-as-a-Service offering, OpenChannel has now pivoted to provide a particularly interesting niche for API providers who are beginning to see a commercial marketplace emerge around their APIs. OpenChannel is a plugin that API providers can add to any existing developer portal to provide an apps marketplace. Key features of this tool are the ability to help third-party developers register the apps they build on an API provider's platform and then the ability for that provider to manage all marketplace tasks, such as downloads of the apps, analytics, and sales data. Code samples are provided in PHP and Node.js to show API providers how to integrate the templates and an OpenChannel marketplace API into their existing site to create and manage the marketplace element.

Unlike other tools listed here, Pronovix is a software development company that custom-builds developer portals for API providers in Drupal. It works with individual clients to provide a range of custom modules for documentation, community forum engagement, video libraries and example codes. The company is ideally suited to API providers who are already working with Drupal as their content management architecture and need an interoperable solution. Pronovix is interesting to follow as they provide a range of in-depth resources on developer portal best practices and are actively involved in the best practice documentation community.

One of the greatest challenges for any API provider at the maturity stage of fostering its own developer community is understanding which developer resources are most effective and how developers are navigating through the available SDKs, tutorials, sample code applications, and other resources to build their applications and integrations. Having the capacity to analyze engagement metrics from a developer portal, individual content assets, and any hosted app marketplaces can provide strategic insights for a Developer Evangelist and Product Manager when deciding how to prioritize future spending on developer community resources. In the next part of our series, Part 12: Gauging API Success: Knowing What Metrics to Measure we look at the decisions you need to make to put in place an evaluation and impact metrics system for your API strategy, including information regarding how developers are adopting your APIs.