Page MenuHomePhabricator

Check for existing APIs
Closed, ResolvedPublic5 Estimated Story Points

Description

Context

To prevent API producers from repeating existing functionality or services, we want to check for existing services.

Acceptance Criteria
  • Creating a list of places to find a "catalog" of existing services with links
  • (this will be the same as the static list on mediawiki for now, until we can publish on toolhub.
  • List out the steps one should take with the possible outcomes once searching the catalog
  • Document findings within this phabricator task and check with @apaskulin for where to put it
  • Create a Wikipage for the Wikimedia Tech Blog and write a few bullet point notes on this portion of the process

Event Timeline

sdkim set the point value for this task to 5.
sdkim moved this task from Incoming to Must do now on the API Platform board.
sdkim added a subscriber: apaskulin.
nnikkhoui triaged this task as Medium priority.
nnikkhoui moved this task from Must do now to Backlog on the API Platform board.

@apaskulin Do you know if this page was intended to be the home for all API documentation? As in RESTBase APIs, MW REST and Action APIs, any other dangling/POC ones, etc.

@sdkim @BPirkle Would we want to catalog non-productionized apis, as in random ones that have been spun up by teams for experiments as well? Maybe put those in a separate section with a heavy disclaimer "these are unstable and subject to change"?

@apaskulin Do you know if this page was intended to be the home for all API documentation? As in RESTBase APIs, MW REST and Action APIs, any other dangling/POC ones, etc.

I'm not Alex, but my opinion is that at least for some of these, we'd want to link to existing documentation rather than having the documentation actually in the API Portal. RESTBase, for example. That may have been what you meant, but I just wanted to say that for clarity.

@sdkim @BPirkle Would we want to catalog non-productionized apis, as in random ones that have been spun up by teams for experiments as well? Maybe put those in a separate section with a heavy disclaimer "these are unstable and subject to change"?

Very good question. I wouldn't object to catalog notable non-production APIs (with a heavy disclaimer).

There are some arguments against, including:

  • it seems unreasonable to list them all. Would we look at every tool on ToolForge to see if it exposed an API? An incomplete list might be worse than no list at all.
  • that list also seems very likely to become unmaintained. A list of old experimental projects that don't exist anymore might reduce people's confidence in the documentation.
  • putting experimental APIs on the list might expose them to more traffic than they're prepared to handle

However, there may also be special cases that are worth listing. I wouldn't mind listing the Image Suggestion API, for example. So maybe we make an intentionally short list, and also have a heavy disclaimer that there are many more experimental, internal, and non-production APIs that are not listed?

Happy to discuss further.

we'd want to link to existing documentation rather than having the documentation actually in the API Portal

yes! thanks for clarifying thats what i meant :)

An incomplete list might be worse than no list at all

very fair.

that list also seems very likely to become unmaintained.

also true, but maybe theres something there with generated documentation. @Eevans and i were discussing alternatives to OpenAPI yesterday and having a way to make this automated without having to maintain documentation in multiple places. I know that theres a job in CI that will publish docs to https://doc.wikimedia.org/ automatically for you, so something built in to CI would be coo.

@apaskulin Do you know if this page was intended to be the home for all API documentation? As in RESTBase APIs, MW REST and Action APIs, any other dangling/POC ones, etc.

No, it was not. Currently, the API Portal is only for APIs proxied through the Gateway. Those APIs can be browsed here. I'm working with Seve to define a new scope for the Portal (T289183) that will meet our needs and that I can use to create a new information architecture (which, depending on the scope, could include a place for a catalog of all APIs).

It seems like this task is just looking for a list of existing APIs. If it makes for a helpful starting point, here's what I have in my notes:

This list is about two years old, so it's definitely missing stuff like image suggestions.

@apaskulin you beautiful soul thank you for compiling this i only had like half of these in my notes. thank you, i will start with this and add more!

@apaskulin Any thoughts of where this list should exist on wiki? Wikitech? MediaWiki?

I don't think we can close this task without first speaking with the toolhub team about somehow getting our API documentation up there! Draft list is culminating on mediawiki for now.

I think it is okay if we have a static manual "catalog" for the example API. I wouldn't require toolhub to be within scope for this to complete

List of questions to answer after searching the catalog:

  • Does an API already exist that meets my needs?
    • If it does not meet my needs exactly, can I fork it and add additional functionality where I need it?
    • If it does meet my needs, where can I get linked to documentation on how to consume it appropriately?
  • How do I select which API to use when there are multiple that accomplish the same thing? (e.g. article content APIs)
nnikkhoui updated the task description. (Show Details)
nnikkhoui updated the task description. (Show Details)
nnikkhoui updated the task description. (Show Details)
nnikkhoui moved this task from Backlog to Should do next on the API Platform board.