Page Previews/API Specification - Revision history

Nardog: /* noexcerpt */ typo: https://codesearch.wmcloud.org/search/?q=%5Cbnoexcerpts%5Cb

2023-09-14T19:31:41Z

noexcerpt: typo: https://codesearch.wmcloud.org/search/?q=%5Cbnoexcerpts%5Cb

← Older revision		Revision as of 19:31, 14 September 2023
Line 58:		Line 58:
	{{Implemented\|0=https://gerrit.wikimedia.org/r/370694}}		{{Implemented\|0=https://gerrit.wikimedia.org/r/370694}}

	=== <code>~~noexcerpts~~</code> ===		=== <code>noexcerpt</code> ===
	The API '''must''' remove any element with the <code>~~noexcerpts~~</code> class to replicate the current behaviour of [[Extension:TextExtracts\|TextExtracts]].		The API '''must''' remove any element with the <code>noexcerpt</code> class to replicate the current behaviour of [[Extension:TextExtracts\|TextExtracts]].

	{{Implemented\|0=https://gerrit.wikimedia.org/r/370694}}		{{Implemented\|0=https://gerrit.wikimedia.org/r/370694}}

Phuedx (WMF) at 15:59, 17 July 2018

2018-07-17T15:59:26Z

← Older revision		Revision as of 15:59, 17 July 2018
Line 110:		Line 110:
	\|?Image		\|?Image
	\|The original of the image associated with the page as determined by [[Extension:PageImages\|PageImages]]. By default, this property '''should not''' be present.		\|The original of the image associated with the page as determined by [[Extension:PageImages\|PageImages]]. By default, this property '''should not''' be present.
	\|-
	\|wikidata_label
	\|?String
	\|The label of the Wikidata item. By default, this property '''should not''' be present.
	\|-		\|-
	\|wikidata_description		\|wikidata_description
	\|?String		\|?String
	\|The description of the Wikidata item.		\|The description of the Wikidata item.
	\|}		\|}
	The new summary endpoint will hydrate these properties with the additional fields specific to summaries:		The new summary endpoint will hydrate these properties with the additional fields specific to summaries:
Line 206:		Line 202:
	The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.		The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.

	The <code>extract</code> ~~property~~ '''must''' be set to <code>""</code>.		The <code>extract</code> and <code>extract_html</code> properties '''must''' be set to <code>""</code>.

	The <code>extract_html</code> property '''must''' be set to <code>""</code>.

	{{Implemented}}		{{Implemented}}
Line 217:		Line 211:
	The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.		The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.

	The <code>extract</code> ~~property~~ '''must''' be set to <code>""</code>.		The <code>extract</code> and <code>extract_html</code> properties '''must''' be set to <code>""</code>.

	The <code>extract_html</code> property '''must''' be set to <code>""</code>.

	{{Implemented}}		{{Implemented}}
Line 268:		Line 260:
	The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.		The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.

	The <code>extract</code> ~~property~~ '''must''' be set to <code>""</code>.		The <code>extract</code> and <code>extract_html</code> properties '''must''' be set to <code>""</code>.

	The <code>extract_html</code> property '''must''' be set to <code>""</code>.

	== Responses for Wikidata (from [[phab:T111231\|T111231: Page previews for Wikidata]]) ==		== Responses for Wikidata (from [[phab:T111231\|T111231: Page previews for Wikidata]]) ==
Line 277:		Line 267:
	This overrides the "For a page in the wiki's content namespace" case above.		This overrides the "For a page in the wiki's content namespace" case above.

	The <code>type</code> property ~~of the response~~ '''must''' be set to "wikidata_preview".		The <code>type</code> property '''must''' be set to "wikidata_preview".

			All members of the <code>titles</code> property object '''must''' be set to their equivalent of the item's label.

	The <code>~~wikidata_label~~</code> property ~~of the response '''~~must~~'''~~ be set to the item's ~~label~~.		The <code>extract</code> property must be set to the item's description.

	If the item has [[wikidata:Property:P18\|the image property set]] (to I):		If the item has [[wikidata:Property:P18\|the image property set]] (to I):
	* The <code>image</code> property ~~of the response~~ '''must''' be set to the <code>Image</code> object that represents the Wikimedia Commons file referenced by I.		* The <code>image</code> property '''must''' be set to the <code>Image</code> object that represents the Wikimedia Commons file referenced by I.

	* The <code>thumbnail</code> property ~~of the response~~ '''must''' be set to the <code>Image</code> object that represents the corresponding thumbnail.		* The <code>thumbnail</code> property '''must''' be set to the <code>Image</code> object that represents the corresponding thumbnail.

	===== Notes =====		===== Notes =====
Line 291:		Line 283:
	The response should be the same as the ''For a Wikidata item'' case apart from the following:		The response should be the same as the ''For a Wikidata item'' case apart from the following:

	The <code>~~wikidata_description~~</code> ~~property~~ of the response '''must''' be set to <code>""</code>.		The <code>extract</code> and <code>extract_html</code> properties of the response '''must''' be set to <code>""</code>.

NRay (WMF): Fix grammar

2018-07-11T19:58:28Z

Fix grammar

← Older revision		Revision as of 19:58, 11 July 2018
Line 7:		Line 7:
	Up until now, we've ''mostly'' gotten away with using the <code>prop=extracts</code> MediaWiki API provided by [[Extension:TextExtracts\|TextExtracts]] and [[RESTBase]] to allow us to scale out [[Page Previews]] to a couple of large Wikipedias without issue.		Up until now, we've ''mostly'' gotten away with using the <code>prop=extracts</code> MediaWiki API provided by [[Extension:TextExtracts\|TextExtracts]] and [[RESTBase]] to allow us to scale out [[Page Previews]] to a couple of large Wikipedias without issue.

	However, the requirement that certain classes of pages should be handled differently means that [[Extension:TextExtracts\|TextExtracts]] is no longer the most appropriate place to house the notion of what a page preview. We should aim to keep [[Extension:TextExtracts\|TextExtracts]] as simple and as general as possible. It may be that we compose the <code>prop=extracts</code> API and the new Page Preview API rather than integrating them but this is not a goal of this work.		However, the requirement that certain classes of pages should be handled differently means that [[Extension:TextExtracts\|TextExtracts]] is no longer the most appropriate place to house the notion of what a page preview is. We should aim to keep [[Extension:TextExtracts\|TextExtracts]] as simple and as general as possible. It may be that we compose the <code>prop=extracts</code> API and the new Page Preview API rather than integrating them but this is not a goal of this work.

	To be clear, the primary goal of this work is to minimise the amount of text/HTML processing in the Page Previews client: the less work the client has to do to display a preview, the better.		To be clear, the primary goal of this work is to minimise the amount of text/HTML processing in the Page Previews client: the less work the client has to do to display a preview, the better.

Kaldari: Adding note

2018-03-17T00:10:42Z

Adding note

← Older revision		Revision as of 00:10, 17 March 2018
Line 1:		Line 1:
			{{Note\|For documentation on the completed API, see [[Page Content Service]] and the [https://en.wikipedia.org/api/rest_v1/#/ live API spec].}}

	This article outlines the specification for a new Node.js based API to generate summaries for MediaWiki based wikis that replaces the existing TextExtracts API.		This article outlines the specification for a new Node.js based API to generate summaries for MediaWiki based wikis that replaces the existing TextExtracts API.

Jdlrobson at 21:56, 16 March 2018

2018-03-16T21:56:38Z

← Older revision		Revision as of 21:56, 16 March 2018
Line 1:		Line 1:
			This article outlines the specification for a new Node.js based API to generate summaries for MediaWiki based wikis that replaces the existing TextExtracts API.

			== Background & Motivation ==

	Up until now, we've ''mostly'' gotten away with using the <code>prop=extracts</code> MediaWiki API provided by [[Extension:TextExtracts\|TextExtracts]] and [[RESTBase]] to allow us to scale out [[Page Previews]] to a couple of large Wikipedias without issue.		Up until now, we've ''mostly'' gotten away with using the <code>prop=extracts</code> MediaWiki API provided by [[Extension:TextExtracts\|TextExtracts]] and [[RESTBase]] to allow us to scale out [[Page Previews]] to a couple of large Wikipedias without issue.

Line 4:		Line 8:

	To be clear, the primary goal of this work is to minimise the amount of text/HTML processing in the Page Previews client: the less work the client has to do to display a preview, the better.		To be clear, the primary goal of this work is to minimise the amount of text/HTML processing in the Page Previews client: the less work the client has to do to display a preview, the better.
			== The specification ==

	=== Intros ===		=== Intros ===

MHolloway (WMF): Update to reflect sending empty extracts and 200s instead of 204s

2018-02-12T19:20:12Z

Update to reflect sending empty extracts and 200s instead of 204s

← Older revision		Revision as of 19:20, 12 February 2018
Line 195:		Line 195:

	=== For a page outside of the wiki's content namespaces ===		=== For a page outside of the wiki's content namespaces ===
	The Page Preview API '''must''' respond with ~~204~~ ~~No Content~~.		The Page Preview API '''must''' respond with 200 OK.

	The ~~response~~ ~~body~~ '''must''' be ~~empty~~.		The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.

			The <code>extract</code> property '''must''' be set to <code>""</code>.

			The <code>extract_html</code> property '''must''' be set to <code>""</code>.

	{{Implemented}}		{{Implemented}}

	=== For a page that doesn't use the wikitext, wikibase-item, or wikibase-property content model ===		=== For a page that doesn't use the wikitext, wikibase-item, or wikibase-property content model ===
	The Page Preview API '''must''' respond with ~~204~~ ~~No Content~~.		The Page Preview API '''must''' respond with 200 OK.

	The ~~response~~ ~~body~~ '''must''' be ~~empty~~.		The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.

			The <code>extract</code> property '''must''' be set to <code>""</code>.

			The <code>extract_html</code> property '''must''' be set to <code>""</code>.

	{{Implemented}}		{{Implemented}}
Line 247:		Line 255:
	<s>The <code>Location</code> HTTP header '''must''' be set to the URL that will get the intro for the target page.</s>		<s>The <code>Location</code> HTTP header '''must''' be set to the URL that will get the intro for the target page.</s>

	RESTBase handles redirects transparently to the underlying service (see [[phab:T176517#3634838\|T176517#3634838]]).		'''Note:''' RESTBase handles redirects transparently to the underlying service (see [[phab:T176517#3634838\|T176517#3634838]]).

	The Page Preview API '''must''' respond with ~~204~~ ~~No Content~~.		The Page Preview API '''must''' respond with 200 OK.

	The ~~response~~ ~~body~~ '''must''' be ~~empty~~.		The <code>type</code> property of the response '''must''' be set to <code>"no-extract"</code>.

			The <code>extract</code> property '''must''' be set to <code>""</code>.

			The <code>extract_html</code> property '''must''' be set to <code>""</code>.

	== Responses for Wikidata (from [[phab:T111231\|T111231: Page previews for Wikidata]]) ==		== Responses for Wikidata (from [[phab:T111231\|T111231: Page previews for Wikidata]]) ==

CKoerner (WMF): CKoerner (WMF) moved page User:Phuedx (WMF)/Reading/Web/Page Preview API to Page Previews/API Specification: Ready for prime time

2018-01-11T16:31:21Z

CKoerner (WMF) moved page User:Phuedx (WMF)/Reading/Web/Page Preview API to Page Previews/API Specification: Ready for prime time

← Older revision	Revision as of 16:31, 11 January 2018
(No difference)

Jdlrobson: /* Markup allowed in an intro */

2017-12-07T19:53:36Z

Markup allowed in an intro

← Older revision		Revision as of 19:53, 7 December 2017
Line 55:		Line 55:

	{{Implemented\|0=https://gerrit.wikimedia.org/r/370694}}		{{Implemented\|0=https://gerrit.wikimedia.org/r/370694}}

			=== Line breaks ===
			It is assumed that any line breaks in the summary are necessary for the display of the content. We thus do not remove any instance of a line break that appears in the lead paragraph of a summary.

	== Request ==		== Request ==

Jdlrobson: /* Responses */

2017-10-17T18:23:30Z

Responses

← Older revision		Revision as of 18:23, 17 October 2017
Line 131:		Line 131:
	\|The titles of the first N links from the disambiguation page. By default, this property '''should not''' be present.		\|The titles of the first N links from the disambiguation page. By default, this property '''should not''' be present.
	\|}		\|}
			{{Done}}
	{{In progress\|https://gerrit.wikimedia.org/r/370694}}

	Where an <code>Image</code> type property '''must''' have the following properties:		Where an <code>Image</code> type property '''must''' have the following properties:

Phuedx (WMF): Update "For a page that redirects to another page" case in light of https://phabricator.wikimedia.org/T176517#3634838.

2017-09-26T12:06:07Z

Update "For a page that redirects to another page" case in light of https://phabricator.wikimedia.org/T176517#3634838.

← Older revision		Revision as of 12:06, 26 September 2017
Line 239:		Line 239:
	{{Implemented}}		{{Implemented}}

		⚫	=== For a page that redirects to another page ===
	=== Responses behaviour (inherited from RESTBase; out of scope for summary endpoint) ===
		⚫	<s>The Page Preview API '''must''' respond with 302 Found.</s>

		⚫	<s>The <code>Location</code> HTTP header '''must''' be set to the URL that will get the intro for the target page.</s>
⚫	==== For a page that redirects to another page ====
⚫	The Page Preview API '''must''' respond with 302 Found.

			RESTBase handles redirects transparently to the underlying service (see [[phab:T176517#3634838\|T176517#3634838]]).
⚫	The <code>Location</code> HTTP header '''must''' be set to the URL that will get the intro for the target page.

	The ~~response~~ ~~body~~ '''must''' be ~~empty~~.		The Page Preview API '''must''' respond with 204 No Content.

			The response body '''must''' be empty.
	{{Implemented}}

	== Responses for Wikidata (from [[phab:T111231\|T111231: Page previews for Wikidata]]) ==		== Responses for Wikidata (from [[phab:T111231\|T111231: Page previews for Wikidata]]) ==