Page MenuHomePhabricator

Establish consistent strategy for namespaces in the API gateway
Open, Needs TriagePublic

Description

Background

Endpoints in the API gateway share a URL structure that begins with api.wikimedia.org/{namespace}. Namespaces are currently used to group endpoints, either by function or by origin. To make the gateway (and by extension, the API Portal) understandable by users both inside and outside WMF, we should decide on a consistent strategy for how to group endpoints using namespaces, based on the capabilities and user needs.

Current examples:

  • MediaWiki Core REST API endpoints under /core
  • Short description endpoints under /core
  • Wikifeeds endpoints under /feed
  • Link recommendation endpoints under /service/linkrecommendation

Versioning: Currently, endpoints in the gateway are versioned by namespace using semantic versioning. This means that if any endpoint in a namespace undergoes a backwards-incompatible change, all endpoints in that namespace must have a version increase.

Expected behavior

There is a clear strategy for namespaces so that there is an obvious place to add new APIs to the gateway

Observed behavior

There are multiple namespace strategies in use, making it unclear where new APIs should be added

Acceptance Criteria

  • A generalized first draft of API namespaces has been published to API Portal Wiki page
  • The upcoming APIs getting published to API Portal have a clear namespace they should fall into:
    • Wikibase REST API > /entities
    • Liftwing REST API > /inferences

Event Timeline

sdkim updated the task description. (Show Details)

For what we know right now, we have come up with the namespace for Liftwing's REST APIs that plan to publish under "inferences".

The reasoning behind this is that not all models provided through the API portal are guaranteed to be ML-based, so we've removed that. Discussing the namespace "model" came up and is also not accurate as there might me non-model things that make predictions such as algorithms. But both models and algorithms align under inferences. One anecdote to reference is Google's Cloud Inference API.

The one example that we have and could restructure is /link-recommendations to put under the inference namespace as follows:
/inferences/suggestions/links or /inferences/suggestions/hyperlinks. This would be suitable for the upcoming image suggestions and content translation suggestions that would fit within this resource.

Addressing the upcoming Wikibase REST API addition to the API Platform, API resources will live under the "entities" namespace.

A distinct ontology has not been standardized or addressed at this time, but there is still value in iteratively releasing more clear interfaces than what is currently being provided through the action API. As an "entity" current exists as a first class object and we want to provide consistency with what is currently understood as the Wikidata data model, designating its' own namespace will be the approach.

Next steps are soliciting feedback from the Wikidata team to see if any use cases or scenarios break this paradigm.

Next steps are soliciting feedback from the Wikidata team to see if any use cases or scenarios break this paradigm.

Confirmed, no immediate objections from Wikidata via @WMDE-leszek

A first draft of potential namespaces with some example resources:

api.wikimedia.org/
user

  • /{id}
    • /preferences
    • /notifications

media

  • /articles
    • /{title}
      • /history
      • /summary
  • /images
    • /{title}

stats

  • /metrics
    • /page-views
    • /unique-devices
  • /trends
    • /most-viewed

inferences

  • /models

entities

  • /{id}