Page MenuHomePhabricator

No generic endpoint to download entity data
Open, Needs TriagePublic

Description

If the endpoint to download item data looks like /entities/items/{entity_id}, then I worry that people will try to handle generic entities with code like this:

entity_id = ...

entity_type = {
    'Q': 'item',
    'P': 'property',
    'L': 'lexeme',
    'M': 'mediainfo',
}[entity_id[0]] # KeyError on unknown prefix

if entity_type.endswith('y'):
    entity_type_plural = entity_type[:-1] + 'ies'
elif entity_type.endswith('s'):
    entity_type_plural = entity_type + 'es'
else:
    entity_type_plural = entity_type + 's'

endpoint = f'/entities/{entity_type_plural}/{entity_id}'

Event Timeline

Would it do justice to the idea of the ticket to alternatively express the concern as

The entity type name inside of the path is redundant as that is already encoded in the first letter of the entity id

?

In the envisioned use case, what would the users of those "generic entities" do next - which response schema (properties, ...) would they expect?

We identified that one of the areas we should tackle here is the TBA in https://github.com/wmde/wikibase-rest-api-proposal/blob/master/DECISION-RESEARCH.md#entityitemq42-vs-entityq42

Some more thoughts would be appreciated from @Lucas_Werkmeister_WMDE regarding T264086#6504783

TBA ticket for filling in the TBA

Would it do justice to the idea of the ticket to alternatively express the concern as

The entity type name inside of the path is redundant as that is already encoded in the first letter of the entity id

?

That, plus the extra complication by the use of the plural form in the URLs. (The principles explain why singular vs. plural should be chosen consistently, but I think using singular everywhere would be simpler.)

In the envisioned use case, what would the users of those "generic entities" do next - which response schema (properties, ...) would they expect?

Try to look up statements, for instance, which mostly have the same response schema between entity types. (The decision of WikibaseMediaInfo to put them under "statements", not "claims", has already caused some pain for tool developers: see T149410.)

Even if the schemas partially diverge, I don’t see the point in intentionally making people’s lives harder by putting them under different entry points. Just let me get the data of any entity and then I’ll see what I can do with it.

So I'm interpreting this as (please correct if beside the point)

  1. omit the entity type from the path altogether
  2. alternatively (if there are documented reasons why the entity type should stay in the path) it should at least be singular instead

So tying this into Special:EntityData too, we don't expect an entity type to be passed in there.
So the assumption that the type is always somehow encoded in the ID is pretty baked in throughout Wikibase.

I just wrote https://github.com/wmde/wikibase-rest-api-proposal/pull/110 documenting the current status quo in this general area (with /entities/<type>).
But perhaps we would want to iterate on from that current state before implementation.