What makes a developer portal stand out in guiding non-REST API integration journeys?
We are looking for developer portals that improve API reference documentation for a portfolio including GraphQL, asynchronous APIs, or other APIs. Success in this category means that a user is experiencing no obstacles when integrating, finding extras to speed up their work, learning how to find support if needed, and figuring out how to maintain an integration with non-REST APIs.
If multiple non-REST API types are documented, how do you help users comprehend the integration style differences and create a cohesive whole?
These developer portals serve their audience well with an engaging design, reference topics, and being creative in making the API reference documentation journey easy and discoverable.
Evaluation includes navigation, appearance, utility, how easy to use, and completeness.
Award Criteria
Questions to ask:
- How do users find relevant information regardless of API type (REST, GraphQL, event-driven, etc.)?
-
Is content structured and scoped appropriately, or is it everything and the kitchen sink?
-
As a registered user, can I access information specific to my use case or API entitlements?
-
How does your devportal improve on basic API reference documentation from an end user's point of view?
-
What special guidance is provided to ease a user’s journey into using the non-REST APIs? How is the user’s conceptual understanding of the domain and its processes supported?
-
How do you support developer needs? E.g. language-specific code examples, interactive docs, "try it out" features, sandboxes, anchor links, dark mode, intuitive navigation? In what ways does the devportal go beyond basic reference documentation to enhance usability?
-
How do users find solutions when problems occur (e.g. error resolution, FAQs, diagnostics)? How are versioning and change tracking communicated to end users?
