Page MenuHomePhabricator

๐Ÿ“Ž Get a sitelink for a given site
Closed, ResolvedPublic5 Estimated Story Points


As tool builder I want to read data of all sitelinks of a particular wiki on an item so that I can use them in my tool.

Acceptance criteria:

  • Following endpoint is developed:

GET /entities/items/{item_id}/sitelinks/{site_id}

  • Following error cases have to be considered:
HTTP response coderesponse payload
Item does not exist404"code": "item-not-found"
"message": "Could not find an item with the ID: {item_id}"
Invalid item ID400"code": "invalid-item-id"
"message": "Not a valid item ID: <ITEM_ID>"
Sitelink not defined for item404"code": "sitelink-not-defined"
"message": "No sitelink found for the ID: {item_id} for the site {site_id}"
Invalid site ID400"code": "invalid-site-id"
"message": "Not a valid site ID: <SITE_ID>"


  • Handle HTTP conditional request headers as in GET /entities/items/{item_id}/statements
  • Handle user authentication/authorization like in GET /entities/items/{item_id}/statements
  • Items that have been redirected should be handled like GET /entities/items/labels/en

Possibly relevant pointers:

Task breakdown notes

  • add GET /entities/items/{item_id}/sitelinks/{site_id} to OAS
  • create SiteLinkRetriever interface and implementation
    • interface method signature SiteLinkRetriever::getSiteLink( ItemId $id, string $siteId ): SiteLink
    • using SiteLinkLookup and SiteLinksReadModelConverter
  • happy path
  • validation
    • create a site id request validator. SiteList::getGlobalIdentifiers() might be a good place to get the list of valid sites from
  • item existence check and redirect handling
  • respond 404 if the site link for the requested site does not exist
  • apply middlewares to the get sitelink route + e2e tests and RouteHandlersTest
  • spec tests
  • mark ready for prod

Event Timeline

Jakob_WMDE renamed this task from Get a sitelink for a given wiki to ๐Ÿ“Ž Get a sitelink for a given wiki.Jan 4 2024, 11:31 AM
Jakob_WMDE updated the task description. (Show Details)

Hello @Ifrahkhanyaree_WMDE
Regarding the 404 Sitelink does not exist for wiki error, Do you think we should change the following:
1- change the error title in the table from Sitelink does not exist for wiki to Sitelink not defined for the item
2- change the error code from Sitelink does not exist to sitelink-not-defined.
3- change the error message from No sitelinks found for the ID: {item_id} for the wiki {site_id} to No sitelinks found for the ID: {item_id} for the site {site_id}

The reason behind the changes is that when a single resource of an item is not there, we usually use the term "not defined" e.g. get an item's single label.


I think the reasoning makes sense and I'd also keep it aligned to how we've done it in the past. I'll make the changes in a few minutes

I'm wondering (and correct if my technical knowledge is wrong) - when we have the GET all possible sitelinks for an item endpoint, and there's no endpoints - would we resort to an error or just send an empty list back? What is the "standard"? I'd assume it's the latter? cc @WMDE-leszek

AFAIK, when requesting a list of resources and there is none we return an empty object, e.g. returning all (labels, descriptions, aliases, sitelinks) of an item.
when requesting a single resource and the resource is not found, we return a 404 error, e.g. returning a single (label in a specific language, single sitelink,...) of an item.

So for your question, yes, the latter is the standard, as we are returning the whole list anyway, either a sitelinks list or an empty list (object).

While requesting a single sitelink is something we are requesting specifically based on a site id, so if it's not there, the resource we are asking for is not there, that's why we return a 404 not found error response.

yup, as @Muhammad_Yasser_Jazirahly_WMDE said above. If there is no sitelinks, and in particular no sitelink to 'enwiki' sitem the expected responses would be
../sitelinks -> {} (empty "map") 200 HTTP code
../sitelinks/enwiki -> HTTP 404 no sitelink defined for site "enwiki" or something along these lines

WMDE-leszek renamed this task from ๐Ÿ“Ž Get a sitelink for a given wiki to ๐Ÿ“Ž Get a sitelink for a given site.Jan 9 2024, 11:12 AM

Hello @Ifrahkhanyaree_WMDE
Maybe it's a late question (of course it's), but late is better than never :3

Should we add the site id to the response?

so the response should be like this:

   "title": "",
   "badges": [],
   "url": ""

or this:

   "site_id": {
	"title": "",
	"badges": [],
	"url": ""

cc: @WMDE-leszek

Seems like Action API does indeed respond with the site id (but not the URL, though I'm happy to keep the way Muhammad showed it). So, I'd have a strong preference to your suggestion then unless @WMDE-leszek says otherwise.

ok, I'll make sure to have the site id in the response in addition to the URL, unless @WMDE-leszek says otherwise.

apologies, I missed phabricator notifications about those pings. The former structure is intentional, as it is in-line with how Wikibase REST API works overall. Basically it goes from the "higher level" item data structure, and more detailed "paths" relate to "traversing" the data tree. Hence when asked for sitelink data for a given site it is expected the API would give the data of it, a value of the "site_id" keyed object in sitelinks list.

Action API uses slightly different logic, showing data of all sitelinks, hence it would always use "site_id" key, despite repeating the "site" in the value as well. That's been deliberate Action API data structure decision, that Wikibase REST API does not follow.

This conversation made me realize that the difference in sitelink data representation in Wikibase REST API and Wikibase Action API have not been documented, so created a task stub for it: T355659