Description

We are approaching our MVP threshold and will soon be advertising the Attribution API to a broader set of internal stakeholders and potential partners. Because of that, we need to present higher quality documentation and ensure the API meets our own API Platform expectations.

Conditions of acceptance

• Update API description to read: "The Attribution API provides well-structured attribution data for content across Wikimedia projects. For more information about attribution guidelines, expectations, and style guides when reusing Wikimedia content, see the Attribution Framework."
• Update endpoint summary to read "Get attribution information for a page."
• Update endpoint description to read

Attribution signals are the individual elements that keep Wikimedia projects visible when their content is surfaced in external contexts. Signals provide direct acknowledgment and access to sources, and present additional information that helps end users evaluate and engage with the knowledge they encounter.

Attribution signals may be pulled for any Wikimedia content page, but are most applicable to articles and media files. Not all information will be returned for every type of page; for example, author is only returned on media files. To differentiate page type differences from missing data, only fields applicable to the given page type are included in the response, and null values are used in cases where data is expected but unavailable.

• Update page title description to: "Page title. To format the title, replace spaces with underscores, and then URL-encode the result (example: Steller%27s_jay). In the API sandbox, replace spaces with underscores, but do not URL-encode (example: Steller's_jay)."
  • Recommendation to change this value at the root in the framework, not specifically for attribution.
• Update redirect field to read "Specifies if redirects should be followed, such as following common page aliases or if a page has moved. Default is set to true."
  • Ensure this default is specified in the OpenAPI spec in addition to the endpoint description. See: https://phabricator.wikimedia.org/T419047 as a global description update.
• Improve description for the 'expand' query parameter:
  • Options for trust_and_relevance and 'calls_to_action` should be specified as an enum.
  • Enum styling applies -- follow example in /v1/page/{title}/history/counts/{type} to display the list of available values beneath the main text.
  • Update description to read: "Allows the caller to include additional types of signals in the response, following the Attribution Framework categories. By default, only Essential signals are returned. Additional categories can be specified in a comma-separated list."
• Improve JSON response schema examples to reflect real world values. Suggestion to include response from an article found on most wikis, such as "Earth"
  • Consider implementing multiple examples -- one for an article, and one for a media file. --> If this becomes too difficult, we can spin out to a separate SPIKE ticket
• Update translation strings with the new content.
  • Continue using experimental flag for this content; we will remove experimental when we promote beta to v1.