Wikidata:REST API feedback round

From Wikidata
Jump to navigation Jump to search

We regularly get feedback that Wikidata (and Wikibase in general) needs an API that’s easier to understand and use in order to get more people to build tools that use data from Wikidata and other Wikibase instances. The existing action API has several problems. The biggest ones are that it’s not a widely used standard, not versioned and that it is not very well suited for Wikibase’ structured data (as opposed to MediaWiki’s usual wikitext). Here we are collecting feedback on the spec and implementation of the new REST API for Wikibase.

What we want to achieve with it[edit]

  • Provide a more industry-standard and versioned way to access and manipulate data in Wikibase. This will make it easier for programmers to get started building tools with and around Wikidata and other Wikibase instances.
  • Provide an API that is more tailored to the Wikibase data model to, for example, make it possible to get exactly the part of an Entity you need instead of the whole entity.
  • Solve a number of issues in the current API that are easier to solve with REST.

Current state[edit]

The specification is available and covers the parts that are already implemented and the ones currently in development.

Please note that the API is still in the experimental development state. There might be changes in the functionality available and API’s behavior that we will not announce separately.

The current state can already do the following[edit]

  • Retrieve the data of an Item with GET /entities/items/{item_id} and filter what fields (i.e. type, labels, descriptions, aliases, statements, sitelinks) are returned when reading the Item data
  • Retrieve all statements of an Item with GET /entities/items/{item_id}/statements
  • Retrieve the data of a single statement of an Item with GET /entities/items/{item_id}/statements/{statement_id} or GET /statements/{statement_id}
  • Conditionally request the data only if it has changed since the specified revision/timestamp (using If-None-Match, If-Modified-Since HTTP headers)
  • Create a statement on an Item with POST /entities/items/{item_id}/statements
  • Authenticate and authorize as a Beta Wikidata user when making edits using the API, as well as provide edit tags and edit comment, and mark an edit as one made by a bot.

To give it a try, here are some REST API calls for an example Item (“house cat”) on Beta Wikidata[edit]

The following things are still missing before it can go live on Wikidata in a first version[edit]

  • Replacing the statement on an Item with PUT /entities/items/{item_id}/statements/{statement_id} or PUT /statements/{statement_id}
  • Editing a statement on an Item with PATCH /entities/items/{item_id}/statements/{statement_id} or PATCH /statements/{statement_id}
  • Removing the statement from an Item with DELETE /entities/items/{item_id}/statements/{statement_id} or DELETE /statements/{statement_id}
  • Automated edit summaries

The following will likely not be available in the first version but follow later[edit]

  • Creating or deleting an Item
  • Getting a statement from an Item based on the Property ID in the statement
  • Any operation (reading, adding, editing, removing) on sitelinks, labels, descriptions and aliases
  • Any operation on entity types other than Items (i.e. Properties, Lexemes, …)
  • Translated error messages

Timeline and updates[edit]

  • August 2022 - Feedback on current development state on Beta Wikidata.
  • October 2021 - Early feedback on the proposed implementation plan; design of the REST API, its scope and specifications.

Feedback[edit]

At any point, feel free to give feedback on this talk page. Updates will be announced on the usual communication channels (Project Chat, weekly newsletter).

Give feedback