Our previous article, Which API management tool, explained the choice overload of options for API development platforms, gateways, and management solutions.
In this article we explore the requirements used to decide your API development platform, API gateway, or API management solution and why you should plan your DevPortal in parallel.
Operational maturity in relation to API management tools
With or without API management tools, a documentation portal is a requirement for good software development practices.
- API development platforms address the needs of the developer or project.
- API Gateway or API Management Platforms address the needs of the API program or product.
-
Developer Portals, with integration to API tools, address the business needs of your company or group.
- A separate developer portal can accommodate the need to change API gateway or API management tools as your API program matures.
- A company with many business units may use multiple API gateways that are then sources of friction until a developer portal is introduced as the single common denominator that brings all of the bodies of knowledge together.
-
Developer Portals, without API tools, address the business needs of your company or group.
- A company may have a platform installed locally and write code against it with no REST APIs at all.
- Any specification can be converted to an OAS specification and be rendered even if it is not an API. In this manner, some companies that have REST APIs go for an on-site installation without cloud servers to interface their local services.
- API management tools can be integrated/added at a later date.
Google Apigee API management is recognized for addressing business needs by allowing API developers the flexibility to adapt to their business needs through integration with bespoke Drupal CMS based developer portals such as Pronovix’ Zero Gravity developer portals or Apigee’s Drupal Kickstart distribution.
How do I select my API management tool?
There is a deluge of articles providing comparisons of API management tools from many contenders. The choice of tool is based on how well they meet your needs. But how do you define what your needs are? You have the needs of the API program to measure metrics of success, needs of the upstream developer who produces and maintains the APIs, and the needs of the API consumer to discover and use APIs.
A typical example of how API management tools can be chosen by merit to the upstream developer journey is provided by Mahesh Mahadevan where he outlines 13 points of comparison from a technical perspective (reverse proxy, load balancing, authentication and authorization (role based access control), IP listing, analytics, rate-limiting, transformation, versioning, circuit breaker, WebSocket, gRPC support, caching, and finally, documentation).
Although these types of articles are great for identifying the strengths and weaknesses of API management tools, they also only take the immediate upstream developer needs as listed into consideration. Documentation is provided in the same bubble for which the developer and API provider needs are being met.
The deviation can be better illustrated using results from Smartbear’s 2020 State of the API report. Answers are in order of highest to lowest percent response.
(As an API developer) How do you measure the success of your API?
- Performance
- Uptime/availability
- Usability/developer experience
- Calls made to the API
- Issues logged/resolved
- Number of subscribers/accounts
- Monetization (revenue)
- Retention
As an API Consumer, what are the top three most important characteristics you need in an API?
- Ease of use
- Accurate and detailed documentation
- Responsiveness/performance
- Service reliability/uptime reliability
- Easy to maintain code
- Satisfactory security model
- Changes & bugs are well documented
- Pricing model satisfies requirements
- Time to first API call
- Scalability of underlying architecture
- Support/customer service
- Backed by a trustworthy organization
- Active community/forums
- Uniqueness in the marketplace
What becomes immediately clear is the rationale used to select your API management tool is usually determined by the points outlined in the first question ‘How do you measure the success of your API’. However, to get downstream developers onboard with your API products, you need to be able to fulfill the needs of the second question ‘What are the most important characteristics you need in an API’. The ‘ease of use’ and ‘accurate and detailed documentation’ are rarely of consideration at early stages of API tool selection.
We start to see how providing for these upstream and downstream developer needs vary when we group these requirements by API tool or developer portal functionality.
API development platforms act as a developer workspace promoting
- collaboration,
- consistent API building tools,
- and testing.
API gateways and API management platforms are designed to promote
- the success of your API by supporting and reporting on performance,
- uptime/availability,
- monetization (when applicable),
- user account management and
- most importantly tracking calls made to the API.
- Focus is on collecting data around
- Responsiveness/performance,
- Calls made to the API,
- Issues logged and resolved.
API management platforms intersect with Developer Portals to focus on the following:
- Developer Experience, ease of use
- Onboarding: Time to first API call
- Scalability of underlying architecture
- Support/customer service
- Build trust signals/Backed by a trustworthy organization
- Active APIs/Activity
- Satisfactory security model
- Pricing model satisfies requirements
- Community/forums
- Uniqueness in the marketplace
- Usability or developer experience
- Retention of API consumers
All API tools aim to promote within their respective functionality
- easy to maintain code,
- accurate and detailed documentation,
- well documented changes, and
- well documented issues.
Developer portals support the needs of the API consumer. A good developer portal will
- increase the ease of use,
- provide accurate and detailed information,
- provide indicators to performance and uptime reliability,
- provide an interface where a user can onboard,
- and follow through on appropriate security checks and balances.
How developer portals deliver on requirements
- What are some deeper underlying requirements that feed into ‘ease of use’ and providing ‘accurate and detailed information’?
- A developer portal can reduce the friction leading to the time to the first API call results with the API consumer as a welcome participant in a happy relationship.
- A branded developer portal can help orient and draw the audience to align with developer or digital centric goals.
- A developer portal can host the organization’s marketing information and provide an active means of communication through forums or support/customer service.
- A developer portal can provide the means for understanding pricing models and enter into contracts that work in sync with monetization of APIs, products, or services.
- A developer portal can document the value proposition of your APIs as an important way of ensuring that your users have an easy experience of understanding what you have to offer, why they benefit with illustrative use cases, and why they should sign up to use or collaborate with your products.
- A public facing developer portal can have content that drives SEO to increase findability and discoverability of your API products.
In conclusion, in all cases the organization or program will require ‘ease of use of APIs’ and ‘accurate and detailed documentation’ via a developer portal. The ultimate goal of selecting an API management tool is to meet the operational needs, developer experience needs, and business needs of your API program. The developer portal should be able to withstand changes to API tools as your API program grows. A developer portal should stand alone as an adaptable tool, with integrations to your API management tools, for promoting discovery and documentation of your APIs.
References
- 2020 Forrester Report on API Management Solutions
- 2020 Gartner Magic Quadrant for Full Life Cycle API Management
- Dev.to: Open Source API Gateways?
- Software Testing Help: Top 10 Best API Management Tools with Feature Comparison
- Trust Radius: API Management Tools (& Reviews)
- The new stack: 5 Ways to succeed with an API Gateway
- My experiences with API Gateways (Mahesh Mahadevan)
Special thank you to Apigee’s Kevin Bouwmeester and Raymond Peng for their advice and experience that contributed to this blog series. All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
