API Portal Overview
What is an API Portal?
An API portal serves two functions, firstly to act as a place where customers and partners can understand and consume your API products, and secondly to provide developers with secure access to your APIs and documentation. They often appear on the developer subdomain, e.g. developer.yourorg.com. however, in some cases, you may also find them on the developers or digital subdomains.
API Portals are also known as API Developer Portals and Developer Portals. We prefer the term API portal as it’s more inclusive of non-developer roles, for example, business managers who may need to make the decision on whether to use the API or not and first need to understand the value proposition. They often have limited or no technical skills.
APIs as products are a well-established concept in certain companies and industries. In others, they are emerging as a fundamental concept that underpins the way API strategies are brought to life. An API portal helps you showcase your API products so that your customers and partners understand the value proposition. In addition, it makes it easier for their developers to understand how your APIs work and gives them secure access.
When looking to implement a new API portal the first place you should start is with the developer portal that came bundled with your API management system. As a rule of thumb, if you can use it, then do so. However, a lot of customers find that it doesn’t meet their requirements. Off-the-shelf Developer portals are fine if you just want to enable developer self-service, but as more and more organisations are looking to join the API economy and create new partner ecosystems we need more from our API portals.
Structure of an API portal
Firstly, let’s explore the features of industry-standard API portals.
Developer documentation
One of the pillars of a good API portal is documentation. Good documentation reduces the difficulty of integrating with you. Want more customers and partners? Then make sure your API design and documentation are well thought out and presented in a clear manner on your API portal.
In the case that the decision maker on whether or not to use your API is non-technical, they will always ask the opinion of a developer for their opinion of your API before they sign up. If your API is impossible to understand then no developer will give their go-ahead.
Sharing API credentials
The main point of an API portal is ultimately to allow others to access your APIs. You do this by sharing API credentials with a developer so that they can make API calls. This can be as simple (and insecure) as an API key, or as sophisticated as a full OAuth 2.0 grant flow.
A developer should be able to regenerate API credentials, this is important in case the original credentials have been compromised in some way.
Getting started guide
Most portals will have an accompanying getting started guide to get the developer up to speed quickly. This guide will often include:
- Code samples - Samples of code and SDKs are great for helping the developer understand how to use your APIs. This is especially true since developers are notoriously bad at reading the documentation.
- Auth Guide - How to Authenticate and Authorise an API call, getting a valid API token.
- Support - Guidance on what to do if the developer gets stuck, who can they contact and how.
API products
Also known as API as a Product. It’s taken for granted that if you are running a successful API program you will have API products. By treating APIs as products we are looking for reusability and ease of consumption. We get this by making our APIs with a customer in mind, be that a developer or business persona. Before the concept of API products was invented, we used to just publish whatever APIs we had at that time and hope that someone would use them. Unsurprisingly, this didn’t work.
Monetization support
There are many paths for getting value from your APIs, direct monetization of the API is one. Many Organisations are looking to create new revenue streams with their APIs and need to be able to monetize them.
For example, a Content Management System may have three different product plans for its API:
- Small - $49 - up to 1,000,000 API calls in a month.
- Medium - $149 - From 1,000,000 to 4,000,000 API calls in a month.
- Large - $449 - Over 4,000,000 API calls in a month.
The API portal needs to be able to present these plans, allow the customer to subscribe to a plan and then enforce it i.e. Limit the number of API calls made in a month.
Example use cases
Useful for both technical and non-technical personas. Giving a real-world example of how you intend the API to be used clarifies the usage. Better still, a demo application running on the portal can add another dimension to understanding how the product should work.
Build vs. Buy as a Service
By building, we mean that you will hire developers to code a new website for you and then integrate that with your API management system.
By buy as a service, we mean taking an existing solution off the shelf and making that work with your APIs.
How to Build or Buy an API portal
If you choose not to use the API portal that came bundled with your API Management system then you have two options, either you build your own API portal and connect it or you use an API portal as a Service.
Building your own API portal
Many organisations build their own API portals. There are many advantages to this approach that are outlined in the next section. In order to build your own portal, you’ll need to follow an approach similar to the following:
- Get the budget - convince your internal stakeholders that you need to build an API portal and that they’ll get a return on their investment.
- Get the developers - find the developers either internally or externally with the backend and frontend skills required.
- Run the project - you’ll be needing to run the project, there will be others in your organisation who are interested in the portal and the developers will have questions.
- Connect your API management system - figure out how to connect your API gateway. If you struggle with this one you can always contact us, we’ve done this a lot.
- Deploy - host it on your cloud service of choice as a new application.
- Maintain - find someone to maintain the application taking care of any updates to the API management system.
7 API portals as a Service
If you prefer to buy Software as a Service (SaaS) to building and maintaining your own software, then the following are some of your options for buying an API portal:
- apiable.io - API Portals as a Service - Up and running within an hour. No developer required. Connects to your API gateway.
- Blobr - The best developer portal to grow API adoption.
- Pronovix - We research, build and support developer portals.
- Rapidapi - Accelerate innovation and bring software to market faster with the next-generation API platform.
- Readme - Developer hubs that meet your users where they are.
- Redocly - Plug in your API reference and customize every nook & cranny to wow your API consumers.
- Stoplight - Design, Document & Build APIs Faster
Feature Comparison
Branding
How your API portal looks and feels can vary depending on a) how strict your organisation is about these things and b) your target audience.
Build
One of the main advantages of building your own API portal is the ability to brand it very close to your own style guidelines. Giving developers access to your corporate brand style at the very beginning of the project will enable them to build something consistent with your company identity. One of the best examples of this is Mercedes-Benz they obviously invested a great deal of time and energy into making this in line with the core Mercedes-Benz design philosophy. If the design is an important part of your brand then this is something that you should consider.
Buy as a Service
Conversely, you’ll save a great deal of time and money if you buy a ready-made portal. Most of the portals offered as a Service have some degree of customization on offer from simple logo and colour schemes to custom CSS integration.
How to decide?
Is the additional time and effort required to create a custom portal needed to maintain your brand identity? Is your brand design very important to you?
Do you have a very specific user experience in mind that you can’t buy?
Will you need to hide from your marketing & communications team for the next three years?
API Synchronisation
Either the APIs published on the portal are coupled with the backend API management system and changes in one are reflected in the other, or the portal requires you to onboard them as you would any other API consumer i.e. you provide API credentials for the portal to access the API.
Build
All API management platforms include the possibility to make changes programmatically e.g. get a list of APIs, and subscribe a developer. Building against these Management APIs requires specialist knowledge but is certainly possible and worth doing if you are considering building your own portal.
Buy as a Service
Very few 3rd party API portals are able to offer deep integration with the API management system - notable exceptions include Pronovix (apigee) and Apiable - all others rely on the API Consumer model and therefore API synchronisation is not possible.
How to decide?
If you have a lot of APIs published in your catalogue, and/or these change frequently, then you should seriously consider synchronisation. If you’re using developer analytics in your existing API management system then having the API consumers synchronised back to close the loop is also an advantage.
If you only plan on exposing one or two APIs, security isn’t that important and you don’t need to keep a track of your developer usage then consider a simple integration.
API product support
By which we mean the ability to present the API to roles other than the developer. Non-technical business personas are often the decision-makers when it comes to choosing to use your APIs. If you don’t present the API as a product then it can be difficult for them to understand your value proposition and they’ll look elsewhere. API products usually include:
- High-level Marketing
- Usage examples
- Features
- Plans
- Subscriptions
In some cases, API products may also be directly monetized.
Build
Outside of building some basic marketing pages, building complete product support, with price plans, subscriptions and monetization will consume a great deal of time and effort.
Buy as a Service
Most API portals as a Service offer productization and monetization capabilities.
How to decide?
If you’re looking for advanced API product support then our recommendation is to buy these capabilities. Building them from scratch, even using services like Stripe, will consume a great deal of time.
Unless you have a pressing need to integrate with a specific subscription/payment service provider then you should try to avoid this complexity.
Portal Architecture
Build
If you have very specific requirements that the API portal should be built with a certain development framework then you may need to build it yourself.
Buy as a Service
Portal architectures vary widely, from older PHP/Drupal solutions to more modern React frameworks. Unless your organisation actively prohibits a particular architecture it’s unlikely that this will be a consideration. The underlying Service Level Agreement will be more important.
How to decide?
Most organisations have a preferred technology stack. If you have strong IT stakeholders this can make a difference, they will veto technology they see as obsolete. Building your own portal allows you the freedom to choose the best stack for your organisation.
Entry Costs
Build
Unless you’re building something super simple, it will take a couple of developers around six to nine months to build an API portal from scratch. On top of that, you’ll need someone to run the project, and a selection of API experts thrown in for good measure. Persuading your stakeholders to make the investment can be difficult if you haven’t already been able to demonstrate traction with your APIs yet.
Buy as a Service
Spreading the costs over a longer period of time requires little to no upfront capital investment however you’ll need to keep this annual expenditure in your budget.
How to decide?
If you can easily raise the required budget, have a good case for building the API portal with your stakeholders and can find good developers then consider building your own portal. Else buying as a Service can be a good first step in proving the business case for little capital expenditure.
Maintenance & Support
Build
If you’re planning to build the portal with external resources then ensure there is an ongoing maintenance contract with that agency. This was necessary in order to keep the underlying architecture up to date and in line with updates to the API management system which changes frequently with new versions.
Buy as a Service
Not having to worry about the maintenance and support of the API portal is a major plus, especially if you find it difficult to retain the ongoing services of a development team. Keep an eye on the Service Level Agreement and for any additional costs associated with the maintenance and support.
How to decide?
If your team is already used to maintaining systems over a long period of time then building your own API portal will be just another system on that list. Be especially careful to ensure the know-how on how to integrate with your underlying API management system is retained, this is necessary to implement any changes in the future.
Implementation Speed
Build
Assuming you’ve gotten the budget in place, be prepared to run a lengthy project. The developers are going to have a lot of questions about how to build the portal. Who is the primary user, business or technical? How should it be secured? Should it use your internal identity provider or something more specific? Which content management system should we use? Should it also be mobile-ready?
Buy as a Service
You should be up and running with a base portal between one hour and one week of signing up depending on how easy it is to integrate your API management tool.
How to decide?
Not having to wait months for your API portal to be built will allow you to concentrate on your core competencies like building great API products. On the other hand, if you have bored developers, giving them something interesting to develop can help with retention rates.
API Portal Security
Both the portal itself and the authentication and authorization it provides as a service.
Build
One of the most important questions to answer is - how you can get secure access to the API management system? Emphasis is on the word secure here. Since the portal is responsible for provisioning new API credentials you need to triple-check the security concept to make sure there are no holes. In addition, you make sure that your portal works with the type of Authorization you plan to provide i.e. That the correct fields for OAuth 2.0 are provided to the developer.
Buy as a Service
Some portals you can buy are able to integrate deeply with your API management software out of the box. Ensure that they are able to store your API management credentials in a safe place and that their employees cannot get access. Many portals only support a simple API key for Authorization. For those that do offer OAuth 2.0 support, do they cover all the grant types that you might need?
How to decide?
Build if you have confidence in your ability to implement the security requirements for your organisation. Buy only if your provider can explain how the API / Management system is being protected.
Considerations when buying an API portal as a Service
Shallow vs Deep API integration
As mentioned in the API Synchronisation section above, not all API portal services are able to connect to the API management system (deep integration.) Instead, they use simple API credentials to get access, as would any other API consumer.
Benefits of shallow integration:
- It’s quick and it’s easy. Just add the API portal as you would any other API consumer, with API credentials.
- You don’t need to connect your API management system to the portal.
- It’s possible to monitor the usage to get insights into the traffic.
- Since the API portal as a Service is responsible for acting as a proxy to the API gateway, It’s possible to react to the API call, for example, increase a counter in Monetization cases.
Benefits of deep integration:
- Adding new APIs or resolving retired APIs is automatically synchronised with your API management system.
- API consumption is simple and easy to track.
- Fine-grained access control or changes to rate-limiting with different product plans is straightforward.
- Revoking API access in your API management system will only remove one consumer, not many.
- No additional proxy layer is needed between the API consumer and the API gateway, meaning:
- No additional latency on top of your API traffic, saving, on average, 50 milliseconds per API call.
- Less potential for a security breach
- Reduces one layer and removes a potential point of failure
Can you implement API products and plans?
There’s no reason why an API product can’t be made up of multiple APIs. There’s no reason why different plans can’t have different methods. An API product exists to solve a problem for your customer, everything they need should be contained within.
Are Multiple API consumer roles supported?
Is this just for the developer, or will it work with all my target customers and partners? Unless your target customer is a developer, you need to think about how to describe the value of the API in non-technical terms.
How does it look?
Try to get a demo as soon as possible, or check a reference customer. You don’t want to incur the wrath of marketing.
What’s the underlying technology stack?
It’s worth investigating a little into what technology the API portal was built on. In a worst-case scenario is this something you could take over and run on-premise? What kind of vulnerabilities exist for this technology? Is it built on legacy software?
Can I connect multiple API gateways?
Your organization probably has more than one API gateway, you’re not alone. These can either be from the same supplier but cater for different regions, or then different departments chose different API management vendors. Either way, will you be able to provide one holistic customer and developer journey irrespective of the gateway, or will you need a separate portal for each?
Synchronize your APIs with API gateway connectors
Apiable has plugins for the most popular API management systems, meaning that you’ll have access to your latest API catalogue without needing any external workarounds. What’s more, it will be kept in sync with your gateway, so new API consumers will be added back into your API management system keeping your analytics up to date.
Conclusion
Unless your organisation has strict brand considerations that you must adhere to, or APIs are your core business, we advise you to not build your own portal. Historically a lot of organisations built API portals because they didn’t have any other choice. Now they do, and there are a lot of options on the market for you to investigate. Decision criteria for API portals as a Service include look and feel, support for API products and if you need the portal to be integrated into your API management system or not.
