Table of Contents
What is a Developer Portal?
Developer portals are how developers understand, interact, adopt, monitor, and govern new technologies.
At the heart of developer portals is a resource. This can be an API resource, cloud resource, virtual machines, or any other cloud resource. Portals facilitate the interactions between developers and a resource. Developers thrive when portals help them feel comfortable with the resources. Then, they can take control of their new “space”.
There are many ways to spot an effective portal. In this article, we discuss common aspects of developer portals and provide examples. The first, and probably most important aspect of developer portals is the documentation.
Related: API Marketplace vs Developer Portals
Documentation is a common way to end up on a service’s developer portal for the first time. In my opinion, you can judge the quality of a developer portal by the quality of the documentation. Developers examine documentation and decide if they can understand the service.
Some developer portals offer small examples. Others have tutorials that may demonstrate how to use different programming languages to implement the service. While a developer is looking at the documentation they are constantly calculating the ease of adoption. The easier a developer can adopt a service, the more likely they are to use the service.
Stripe is a service for online credit card payments. Their portal provides clear documentation for parameters, return values, code snippets, and response objects.
Furthermore, they offer in-depth examples. In the image below the example is a hyperlink to another article. On the right side, you can see the code snippet and example response object.
In the above screenshot I have:
- easy to find navigation
- technical aspects of the endpoint
- example response
- option to see a sample request
- code snippet
All of the above aspects combine for a pleasant experience in Stripe’s developer portal.
If I don’t have all the information I need in the documentation then it’s going to slow down my development speed. It can be frustrating to wait on a question, even with companies that have good customer service. Another factor in development speed is sample code. For example, below is an image from an API on the RapidAPI marketplace. The example shows API calls using different programming languages and libraries.
This is common across developer portals. Some offer an interactive input component while others may just show a few code snippets as an example. Code snippets provide a nice starting point for adopting the API resource. Next, let’s talk about developer support.
Developer portals also provide support for their products. Some questions are too complex for the documentation.
A portal can offer live chat or email support. Although some services may offer live chat, a common theme with developer portals is independence.
Developers want to be able to solve their problems. Sometimes the question isn’t urgent, so portals offer an easy way to open up a support ticket to be answered by email at a later time. Later, we will discuss developer independence in greater depth.
In many cases, portals try to steer the developer towards the community forums or the frequently asked questions page.
An example of this is Walmart’s developer portal. Below is an image of the help page in their portal. Most people read from top-to-bottom and left-to-right. Following this common reading convention, you see the image options in this order:
- FAQ (frequently asked questions)
- Contact Support
The idea is that most questions have already been asked and answered. This allows the developer to answer their question faster by finding it an accessible section.
Building a strong developer community has benefits. The community provides a developer with a chance to interact with similar people using the service. Two people may be experiencing the same roadblock and can work together as they formulate a solution.
Community support forums can exist alongside a portal or to supplement portal support.
Netlify is a cloud service provider. Recently, they have created a community support module that works alongside their developer portal.
From the developer portal, you can access the community forums, which takes you to their community homepage.
The developer can search the questions or view discussions by category.
At times, developers move faster than products. This means that stable releases of services are behind what people are doing with the service. Community forums can help developers work to solve common problems. You see this scenario when integrating services for a project.
Monitoring resources is a critical part of any developer portal. Being able to quickly check resource health can provide peace of mind. With an API resource, a developer portal allows the user to monitor the number of requests. Some portals even can view information about individual requests.
Above is the RapidAPI dashboard showing requests that occurred over a short period. In this example, the portal allows the user to peak inside the resource.
Being able to monitor the health of resources in a developer portal is another step that service providers can take to achieving developer independence. If an error occurs, I can quickly identify the exact request. This allows me to iterate on the problem and solve it faster.
Linode is another cloud services provider. On their developer portal, you can monitor the CPU usage of your resource.
Graphical representations accompany different tabs showing the various aspects of a resource that can be monitored. Linode also allows notifications to be sent when CPU usage reaches a maximum level.
Notifications help a developer relax. Being able to know when something is going wrong gives the developer control over their resource. This can build trust between the developer and provider.
API monitoring includes API access management. This is also known as governance.
Just like a building has keys, a developer portal needs access constraints. Resources can exist between developers and organizations. It’s essential to handle who has access to different cloud resources.
When thinking about governance, your mind may immediately jump to malicious intent by a user. However, it is more often the case that a user is accidentally accessing a resource more than they need to be. Another example of unintentional abuse is when a user does not fully understand the resource they are using. They may be making changes that are causing damage elsewhere in the system.
RapidAPI for Teams
This service provides governance capabilities. Furthermore, you can view activity audit trails for your APIs.
In the image above, you can see that there have been activities that include:
- description update
- endpoint add
- API delete
- base URL change
All of the API’s activity takes place inside an organization’s account on RapidAPI for Teams. Therefore, you do not have to view multiple API audit trails.
RapidAPI balances governance and developer independence by ensuring API consumption policies are in place while empowering developers to access APIs on a self-service basis.
All of the portal categories discussed have the common theme of developer independence. Developer portals want to put the power of resources into the hands of developers. This lets them use it as independently as possible.
Developer Independence & Governance
On a smaller scale, having naive restrictions on resources can be manageable. Also, documentation may be lacking if the team is small. This can work, but as the services grow this falls apart.
Documentation, usage examples, and test cases increase developer independence. Having poor API governance can be inefficient and further decrease developer independence.
RapidAPI Enterprise provides:
Access management lets users set API restrictions. Audit trails keep track of what changes are made to the API behind the scenes.
Developer portals give developers a place to understand, interact, adopt, monitor, and govern new technologies.
In this article, we looked at examples of different API portals that demonstrate the ways portals use documentation, support, community, analytics, and governance.
If you are creating a developer portal, your understanding increases by knowing what a developer expects when they are trying to adopt new technology. If you are using a developer portal, your expectations of a portal experience can give you insight into the quality of the service.
What is a developer hub?
A developer hub is a place where developers can share and collaborate on projects, services, etc.
What is an API hub?
An API hub provides an integrated platform that offers tools to connect to and test internal, or external, APIs.
What is an API marketplace?
An API marketplace is where developers can create, share, find, manage, and monitor APIs. API marketplaces can be open to the public or private within an enterprise.