We have agreed that there's an opportunity to improve our API UX by providing more guidance to help users differentiate between our API offerings (reference). This project includes multiple APIs, some of which have overlapping functionality or serve the same use cases in different ways. In order to design an information architecture that reflects that differentiation and guides users through the complexity, we need to:
- Agree on the types of users and tasks (use cases) that should be emphasized, and
- Define which attributes of APIs are relevant for sorting the APIs based on 1)., then
- Capture the values of those attributes for each of the APIs that is in-scope.
For example:
- Example A: If we agree that high-volume users are a key audience (1), what are the attributes of an API that make it a good option for those users (2), and which of our APIs have those attributes(3)?
- Example B: If we agree that content reuse is a key use case (1), what are the attributes of an API that make it a good option for that use case (2), and which of our APIs have those attributes (3)?
In other words: I don't know the answer to "which API is the best option for use case X", or "which API should we recommend for user type Y". We need a better map of this landscape in order to design an information structure that guides people through it.
TODO:
- Determine if more user research or SME interviews are necessary to answer these questions, or if this knowledge already exists somewhere / has already been defined by the teams working on WE5.2. The Developer entry points spreadsheet (restricted access) has a tab "Entry Point summary" with columns for Type of data, Primary persona(s), and Primary use case(s). This is very close to what I think we need, but it may be more efficient to first identify the personas and use cases to prioritize, then catalog the in-scope APIs based on that.
- Identify which characteristics of our APIs are the most relevant and salient to differentiate them, from users' perspectives. Examples/ideas: performance? restrictions? modularity? scope / types of data available? certain functionality? What are the most important differentiating attributes our key audiences are looking for when they're seeking an API to use? The aforementioned spreadsheet (restricted access) has columns for authentication and rate-limited/throttling, but I'm not sure if those are things infrastructure maintainers care about more than end-users.
- Define how we want to recommend APIs: is it by type of user? By use case? Both? Once we answer this, we can then dig into the areas where it's especially unclear which API to choose, or where there's overlap:
- Identify use cases that our APIs have in common and which API should be recommended for which type of user for a given use case
- Identify which (if any) APIs can only be used by certain types of users (i.e. high-volume, commercial, ML applications...?)
The above tasks are necessary to design an IA that meets these aspirations defined in the OKR and product docs:
- "Our docs should provide more opinionated guidance for when one solution should be used instead of or in parallel with another. E.g., in high volume situations we may recommend using the REST API over the Action API as a more performant and sustainable solution.
- Clearly document and differentiate our APIs and intended use cases: API catalog/entry point should introduce the purpose and intended use of each API, clearly differentiating it from others.
Note: this doesn't impact IA or content strategy at the individual API or endpoint level; it is purely about how to design the top-level UX that makes it easier for users to identify an API to try out or start using, without having to build a complex mental model of all the available options.
The only existing content I'm aware of that addresses this:
- https://meta.wikimedia.org/wiki/Research:Data_introduction#Data_domains - Target audience is researchers so APIs are only a small part of the options presented, but they are at least divided into domains and limited to just a couple of the best options in that domain (but this content may now be outdated, too)
- https://www.mediawiki.org/wiki/API - limited to only a few of our APIs, and doesn't provide strong guidance about how or why to pick one API over another
- https://wikitech.wikimedia.org/wiki/API_Portal#Original_content_strategy_(March_2020) - original content strategy for API Portal has section based around use cases which are a combination of content type and general domain of interest