This is the first of an ongoing series of articles where ProgrammableWeb will take a look at API developer portals from various providers to highlight those that are the best in class.
Portals have grown from the days when a static listing of endpoints was considered enough to get users started with your API. Now that APIs have grown into products — and it is imperative for every API provider to treat their internal or external APIs as full-fledged products — the associated portals are expected to exude their product orientation.
In this article, the first ProgrammableWeb Editor's Choice Award for Excellence in Developer Experience (DX) goes to GitHub's API portal. GitHub is both a website and a cloud service that lets developers store their code (aka "code repository"), manage their code by tracking and controlling changes to it, and network with other developers. As the largest host of source code in the world, GitHub is developer-centric and offers a widely used API. With the API, you can integrate the platform with your app to allow for a huge range of possibilities including automated code review, testing and deploying your apps, real-time error monitoring and much more.
This article offers a review of the API portal instead of the API itself. We are judging it based on five broad criteria: how well it helps users understand both the provider and the API, how it goes about establishing trust, the ways in which it helps developers use the API quickly, the quality of the API reference, and what forms of support if offers when developers get stuck.
For each of these five broad criteria, ProgrammableWeb has created a detailed methodology — a developer portal ideal — up to which award candidates are held. It's an ideal that no portal we know of currently satisfies. As a reflection of that "good, bad, and ugly," our winning reviews will document both positive and negative observations in a way that causes you to wonder if an award winner was really worthy. Rest assured that despite the balanced commentary of our editor's choices, the good greatly outweighed the not-so-good. Additionally, when reading any of our Editor's Choice reviews, keep in mind that our analysis was conducted at a point in time after which the features of a developer portal may have changed or improved.
Understanding the Provider and the API
When thinking about your portal, you need to consider the audiences that will be visiting it. Developers will undoubtedly be one segment. But there will also be a number of decision-makers be they product managers, CIOs, CTOs, or even CEOs. This audience often wants to understand what your API can do and how it can help solve their problems. A good portal will help accelerate the learning process by clearly stating the value proposition of the API, using language that focuses on customer outcomes, providing clear use cases and customer stories that support them, and providing product information such as pricing, limits and terms.
When it comes to Github's developer portal, it's very clear what the API is for; it lets developers build apps on the GitHub platform. When you first arrive at the portal, the call to action to learn more about building your app on Github is clear and clicking through further explains why developers would want to build such apps, focusing on automating and improving app dev workflows.
What's missing is some narrative aimed at decision-makers that explains what types of problems the API is good for. While the API may be straightforward to understand, it would be nice if there were some additional customer-focused language that describes some of the outcomes enabled by using the API.
One way of showing users potential outcomes is by including use cases of the API within the documentation or elsewhere. Github's portal doesn't do a great job of highlighting use cases, though it would be unfair to say they are non-existent. Version 3 of Github's RESTful API includes links to a number of Getting Started guides that cover some of the most common use cases. However, this isn't made clear unless the user clicks through a hieraerchy of links as there isn't any narratives explaining why the guides are focused on these topics. Even worse for the GraphQL version of Github's API, use cases are nowhere to be found. The overall impression is that the API is aimed at people who truly understand both the Github platform and the advantages of using GraphQL over its REST counterpart.
One thing GitHub's portal does very well is the way it showcases its app marketplace. The GitHub marketplace lists both Actions (custom logic that performs a needed task) and full-fledged applications. While the portal lacks narrative about what the API can be used for, browsing through the marketplace quickly uncovers the breadth of what is possible including automation of code reviews, automatic testing and code deployment, performance monitoring, project management and much more. While this may seem readily apparent to anyone visiting the marketplace, a narrative that tells this same story is something that's missing from the main portal pages.
One thing curiously missing from the portal is any mention of case studies or customer success stories. Case studies are a wonderful way of helping decision-makers understand the benefits of your product and showing that it can be trusted because of how other organizations are succeeding with it. Given that GitHub is such a massive platform used worldwide, it's odd not to see any customer stories. In fact, they do exist, but only within the main GitHub site. The customer spotlight page which is less about Github's API consumers and more broadly about Github's customers offers well over 40 stories. It would be worth the time to carve out a section of the developer portal that gathers the subset of these stories that reference customers using the API because they are very well done and compelling.
An important part of deciding on an API is the cost associated with consuming it. Ideally, the pricing will be easy to find and understand. The portal doesn't explicitly lay out pricing details though the use of the API is available starting with GitHub's free individual plan. The assumption is that whatever plan you use, individual or team, you have API access. It's not clear if higher plans get you higher rate limits or other perks.
On the other hand, the pages showing API call limits are easy to find, linked under the Guides section for each version of the API. One interesting thing to note is that the rate limits are different for each version due to the differences between REST and GraphQL. We'll touch on this later, but GitHub goes out of their way to help users understand the difference.
Continued on Page 2.