Developer Portal

 What is a Developer Portal?

An API without good documentation is no better than having no API at all. A Developer Portal is more than having good documentation, it is a great way to showcase your thoughtfulness in designing and documenting the API, to engage with the API consumers, and be the central point of conversation between teams.


It sounds great, doesn’t it? But what is a Developer Portal (referred to as portal below) really? To put it simply, a portal is the interface between a set of APIs, SDKs or other interactive digital tools and their stakeholders. It’s worth emphasising that the purpose of a portal is more than meeting the needs of its immediate team (developers, QAs or PMs etc), but also engaging with other business and development professionals.


It is not hard to find a selection of example Developer Portal for the finance industry, like Nasdaq, Dow Jones, SWIFT; or industrial leaders in tech, Twitter, Google, Meta etc. 


Why should you build a Developer Portal?

Perhaps the answer is obvious, but it is worth re-aligning business and technology with the vision. More often than not, enterprises are looking to use the portal as a medium to achieve their API strategies.

Making API Discoverable

The portal should be a trusted source of truth where stakeholders, including developers, come to find tutorials, references, use cases and support of an API easily.

Building Business Value

The portal is the place to showcase the features of the API and the benefits of the product, allowing users to be productive at all stages from pre-sale, integration to support, and shortening time-to-value for API consumers.

Accelerating API Adoption

The quickest way to drive adoption of a new feature in the API is by sharing the knowledge with good documentation, making it easy to access, experiment and integrate across different vertices in the organisation. The portal bridges the gap between business and development teams, and creates an environment for perpetual collaboration and innovation.

How is it done?

Evidently, focusing on presenting the core capabilities of the API and staying engaged with key stakeholders provide tremendous value, there is not really a set of golden standards as such on how the portal can be created. From experience, following are some key aspects of what a well-designed portal should look like:

Target Audience and Access Control

To start with, determine who is the portal’s target audience? 


Depending on the specific API, the target audience could be the public, or it could be inside the company, or a selected group. 


If the portal is not open to everyone, then access control needs to be in place to secure these assets. Having access control brings many other benefits as well, such as selective access to certain API, managing API visibility through authorisation. 


If the portal is public, then making sure the right branding and logo are used is important to reflect the correct image of the company.

API Catalogue 

It is hard to imagine there is only one API in any organisation. In fact, there may be hundreds of APIs where teams have built in isolation. One key capability the portal can bring is increasing visibility and transparency by bringing all these APIs together to form an API catalogue, which will immediately transform it to become a fountain of knowledge and a great conversation starter in cross-team communications.

Knowledge-Based Documentation

A common pattern for creating a portal is: an API team publishes a version of Swagger documentation somewhere, and calls it a developer portal. 


While reference documentation is undoubtedly the foundation to build a minimum viable developer portal, there are a lot of other characteristics, but not limited to, to consider.


  • Step by step setup guides and tutorials to use the API

  • Self-serve API registration

  • Sandbox testing environments

  • Code example describing the full contract from request to response

  • An interactive API console that can show sample responses for each API call

  • Easy search for content

  • Release notes (changelog)

  • Service status

  • Support (methods to contact teams)


There are a lot of online readings and frameworks that can give a good idea of what to expect in documenting an API for the portal to get started quickly. There may not be a  one-size-fits-all recommendation on API documentation and tooling and teams should decide on the most suitable tooling to use

Hosting and Governance

As previously mentioned, the portal is more than just another place for API documentation, it is also a place for writing and publishing documents, blog posts, and onboarding materials. Even if a couple of technical writers produce the minimum amount of content, an infrastructure is needed to host the published content. 


A simplistic approach is to have each API team hosting their own portal alongside their API. But there may be limitations with it, to name a couple: consistency, accessibility.


A more sustainable way to manage the portal is to have a dedicated team building and maintaining it, and freeing up API teams to focus on publishing quality content. By managing the portal centrally, it will also significantly increase the capability of the portal to host a variety of rich contents, such as videos. 

Success Metrics

Given that it is not about whether or not a portal should be created, but how. It is important to measure how effectively the portal delivers business values, and also use the metrics to evaluate the maturity level of the APIs to provide guidance for future development.


The following are some examples of metrics to help drive the conversation with the API teams. If dealing with large-scale public APIs, consider using Engagement Metrics to collect data points at its fullness.

Time to First Request

Time to first request measures the time it takes for a new user to land on the portal to make their first successful API call.


This is a good indicator on how effective the design is, and how easy it is to get going with the documentation provided.

Drop Off Point

Drop off point is on the flip side of time to first successful request, it looks at the problem scenarios: when being on-boarded to the API, what is the reason the user drops off the portal? It could be due to an issue on the server side, or the user experienced a 4xx error. And what were the last API calls before the user left the portal? 


There are many things to investigate and hypothesise. The analysis of those user behaviours can also be fed into the API development roadmap.

Comments

Post a Comment

Popular posts from this blog

A practical guide to Scala Traits

Trait - has a super class of AnyRef   - uses extends  or with for inheriting a trait ( with to inherit multiple traits)   - defines a type   - can be overridden using override  keyword   Trait vs Interface (Java)   - trait can declare fields and main state   - rich vs thin interfaces (every concrete method added to trait makes it richer)   Trait vs Class   - trait can NOT have any class parameters        trait doesn't support coding in this style: class Point(x: Int, y: Int) - super calls are statically bound in classes, but dynamically bound in trait         super.toString  is predicable in classes, but not in trait when mixing   Ordered Trait   Traits as stackable modifications   - order of mixins: right most trait takes effect first   When to use Trait?   - If the behaviour will not be reused, then make it a concrete class   - If it might be reused in multip...
Read more

A Short Guide to AWK

AWK is built to process column-oriented text data, such as tables. In which a file is considered to consist of N records (rows) by M fields (columns) Basic # awk < file ‘{print $2}’ # awk ‘{print $2}’ file file = input file print $2 = 2nd field of the line, awk has whitespace as the default delimiter Delimiter # awk -F: ‘{print $2}’ file -F: = use ‘:’ as delimiter # awk -F ‘[:;]’ ‘{print $2}’ file -F ‘[:;]’ = use multiple delimiter, and parse using EITHER ‘:’ OR ‘;’ # awk -F ‘:;’ ‘{print $2}’ file   -F ‘:;’ = use multiple delimiter, and parse using ':;’ as THE delimiter # awk -F ‘:’+ ‘{print $2}’ file   -F ‘:’+ = use multiple delimiter, to match any number ':' Arithmetic # echo 5 4 | awk '{print $1 + $2}' output is '9', the result of ‘+’ (works as addition) # echo 5 4 | awk '{print $1 $2}' output is '54', to get string concatenation #  echo 5 4 | awk '{print $1, $2}' output is '5 4',...
Read more

How to: Add Watermark to PDFs Programmatically using iTextSharp

Being able to add text or image watermark to PDF files is one of those handy things you can archive via program. The only library required for the little program is iTextSharp . For those who haven't used it yet, iTextSharp is a C# version of iText , which allows you to generate or manipulate PDFs. So let's cut the chitchat, and go straight to the code. By calling 'AddTextWatermark' or 'AddImageWatermark' function with required parameters supplied, you are ready to rock! public void CreateTemplate(string watermarkText, string targetFileName){     var document = new Document();     var pdfWriter = PdfWriter.GetInstance(document, new FileStream(targetFileName, FileMode.Create));     var font = new Font(Font.FontFamily.HELVETICA, 60, Font.NORMAL, BaseColor.LIGHT_GRAY);     document.Open();     // Specify font and alignment of text watermark     ColumnText.ShowTextAligned(pdfWriter.DirectContent, Element.ALIGN_CENTER, new ...
Read more